@shumoku/core · 0.4.0
TypeScript APIリファレンス
TypeScriptとTSDocから生成した公開関数 155 件です。
absenceImpliesRetraction True when absence in a snapshot should be treated as evidence
(retract / mark stale). False when the snapshot 's absence is
meaningless because the node was deliberately not asked.
This is the *critical* anti-footgun call codex flagged: if we
post-filter excluded nodes out of a NetBox snapshot whose status
is `ok` (= absence trusted), the resolver would happily interpret
the missing entry as "NetBox says it 's gone". We never want that. addHttpWarning Add HTTP warning to connection result if URL uses insecure HTTP addLink Add a link between two ports (existing or new).
If fromPortId/toPortId refer to existing ports, use them.
If toTarget is a nodeId (no port), create a new port on that node.
Returns the updated graph with the new link, or null if invalid. addPort Add an unnamed port to a node on the specified side. The port is appended
to `Node.ports` (the data model) and to the resolved-port map (layout).
Label stays empty — the renderer hides labelless ports' label rectangle,
and the user can name it later from the detail panel. alignPortsToPeers 英語の追加説明はありません。 applyOctilinearRoutes Mutates eligible edges: sets `route` to an octilinear polyline (and
mirrors the corner points into `points` for labels / hit testing).
Returns the number of edges routed. applyThemeToCSS Apply theme to CSS variables asEntityId Trust-boundary cast — DB reads, registry mint, wire-format parse.
Use ONLY at: mint, DB row reads, HTTP param boundaries, and tests.
If you find yourself casting mid-logic, fix the signature above you instead. assertLayoutConstraints Standing-fixture gate (engine-v3-migration.md §B4, finally wired):
verify after a layout and — when a BLOCKING constraint is violated —
throw under `NODE_ENV=test` (CI fixtures pin the guarantee), log an
error otherwise. A runtime layout must NEVER fail to render because of
the gate: Bun defaults NODE_ENV to 'development', and throwing there
turned a constraint report into "no diagram at all" (the flat-tree path
on a 1.5k-node graph violates massively — that's a finding for #481,
not a reason to refuse the bake). attachmentKey Stable merge / suppression key for an attachment. `access` is keyed per
protocol (SNMP and SSH are distinct slots); `metrics-binding` is keyed per
metrics source (two metrics sources can each bind one element — but ONE
binding per (source, element) is the invariant; extend with a role segment
if per-metric-role binding is ever needed, don't overload the slot); every
other kind keys by its `kind`. The resolver merges attachments by this key
(highest-priority contribution wins per key) and the human suppresses by it
(`suppressedAttachments`). One definition so merge and suppression never
disagree on what "the same attachment slot" means. autoLayoutFlatTree Lay out a network graph using the flat-tree algorithm,
using the supplied `LayoutEngine` for rules (sizes, gaps,
label widths).
Equivalent to the legacy `layoutNetwork(graph, options)`,
but the engine is now a first-class concept. The same engine
instance can also serve manual placement (`engine.tryPlace`)
so layout and drag-snap stay consistent. bezierEdgePath Build a cubic-Bezier SVG path `d` string from one port to another.
Each port is described by its absolute (x, y) position and which
side of the node it sits on. The path leaves `from` along that
side's outward normal, sweeps through two symmetric control points,
and enters `to` along its own side's inward normal.
`lateralOffset` (optional, on either endpoint) shifts that endpoint
**and** its control point perpendicular to the port's outward
normal, so the curve still leaves / arrives straight along the
normal but starts (or ends) sideways from the port centre. Used by
the router to fan multiple edges sharing one port apart visually
without rerouting through orthogonal segments. Positive = right of
the outward normal in screen coords (y-down). The endpoint *visibly
detaches from the port centre* by the offset — fine for fan-out
decoration but not for tight-tolerance hit testing on the port itself. bezierOffsetPath `bezierEdgePath` translated as a whole by `offset` SVG units along the
chord-perpendicular direction. Used to draw parallel "in" / "out"
lanes for weathermap-style flow overlays.
This is a *parallel translate*, NOT a true cubic offset curve (which
cannot in general be represented exactly as another cubic). All four
control points shift by the same vector, so:
• lane spacing is exactly `2 * |offset|` everywhere along the curve,
• the offset curve never crosses the base curve or the opposite lane
regardless of port-side configuration (incl. same-side U-turns
and adjacent-side L-turns),
• tangents are preserved at every point — but the lane endpoint is
shifted off the port by `(nx, ny)`. Lanes are decorative; they
are not meant to "connect to" the port.
The shift direction is the chord normal (perpendicular to b-a). Sign
convention: in screen coordinates (y-down), `+offset` shifts to the
right-hand side of the chord A→B, `-offset` to the left. Pass
`+offset` and `-offset` for the two lanes; which one ends up labelled
"in" is a data-source semantic, not enforced here.
Computed analytically — no DOM measurement, so callers don't need a
mounted SVGPathElement. bindingInterfaceName The best name to hand the plugin for an interface binding. Identity
(`ifName`) is the durable key; `interfaceName` is the migration / label
fallback. The poll-time resolution layer may refine this against the
source's live interface list, but a name is always derivable here. bpsToLinkWidth Map a raw bits/sec value to the calibrated stroke width. bpsToLinkWidthMode Map bits/sec to stroke width under the given mode. Unknown bandwidth
returns 0 (caller decides the fallback), matching `bpsToLinkWidth`. buildAlertTitle Display title: `"<alertname> - <host>"`, or just the name when no host. buildChildSheetGraph Build a sub-sheet `NetworkGraph` for the given subgraph id — the
filtered nodes/subgraphs/links plus export-connector nodes that
represent cross-boundary links.
This is the layout-free half of what `buildHierarchicalSheets`
does per subgraph. Callers that want to run their own layout
engine (e.g. the interactive editor, which already owns a
`computeNetworkLayout` path) can use this directly and skip the
`LayoutEngine` indirection.
Returns `null` when the requested subgraph isn't in `rootGraph`. buildCompositeRoutingPlan 英語の追加説明はありません。 buildHaHullPath Build the glasses hull path for one redundancy group.
Falls back to a rounded rect over the union bbox when the chain isn't a
clean horizontal row (`fallback: true`), so callers never have to guard —
every group gets SOME hull. buildHierarchicalSheets Build hierarchical sheets from a root graph
Creates child sheets for each subgraph with:
- Filtered nodes (only those belonging to the subgraph and descendants)
- Internal links (both endpoints in subgraph/descendants)
- Nested subgraph definitions
- Export connector nodes/links for boundary connections buildIdentity Build an `Identity` from raw parts, dropping empty values. Returns
`undefined` when nothing identifying was supplied (so callers don't stamp
an empty identity object that the resolver would treat as `unbound`). buildLayoutProblem 英語の追加説明はありません。 cableConnectorForStandard Derive the cable-end connector from the link's effective standard.
The model no longer stores `cable.connector` explicitly — call this
from display / validation code that needs the connector value. cableGradesForStandard Cable grades available given the link's standard. Returns an empty
array when grade isn't a meaningful axis (DAC / AOC) — the UI hides
the third select in that case. cableVariantsForPlug Cable variants for a plug — all standards reachable through that
cage form factor, ordered by speed. For RJ45 this includes 10M /
100M / 1G / 2.5G / 5G / 10G; for SFP+ it includes SR / LR / CR / AOC. chamferCorners Cut each ~90° corner with a 45° chamfer for the metro look. checkLayoutInvariants 英語の追加説明はありません。 classifyIcon Classify a raw icon string into inline-SVG vs URL.
Inline content starts with `<` (either a bare `<path .../>` fragment
or a full `<svg>...</svg>` block). Anything else is treated as a URL,
including `data:` URIs. classifyStandardGroup 英語の追加説明はありません。 collectObstacles Collect all obstacles as centre-based rects, excluding
entities related to `excludeId`. Both nodes and subgraphs
are treated as rectangles. computeEffectivePolicy 英語の追加説明はありません。 computeNetworkLayout Compute layout and return both ResolvedLayout and legacy LayoutResult.
Use this when you need both (e.g., renderer-svg uses ResolvedLayout directly). computeRoleDrivenRanks Role-driven depth rank, robust to UNDIRECTED inventory cables (NetBox/Zabbix
arrow:none). Direction can't be trusted, so the root is chosen by role +
structure (the most peripheral boundary device = WAN edge) and depth is the
BFS distance over the undirected graph — not raw link from→to (which makes a
node whose cable happens to point "outward" a false source, e.g. a server at
the top). High fan-out / thin-link sinks are not traversed through; a second
pass reaches nodes that sit behind them. createEngine Build an engine instance. Stateless across queries (every
call returns the same answer for the same input given the
same config). Memoization is allowed inside; the
`fingerprint` is the cache key. createMemoryFileResolver Browser/in-memory file resolver for testing createNetworkLayoutEngine Create a LayoutEngine that uses the custom network layout + libavoid routing.
Returns LayoutResult for backward compatibility with existing consumers. createNodeFileResolver Node.js file resolver implementation createTheme Create custom theme defaultCableGrade Default grade for a freshly-picked standard. Used when the user
picks/changes the cable medium and we want the third select to land
on a sensible value rather than empty. defaultStandardForCages Propose a sensible default standard given the cages on both ends. deriveMappingFromGraph Derive a legacy `MetricsMapping` from a resolved graph's bindings.
- Node host binding → `mapping.nodes[node.id]`.
- Link interface binding lives on a `NodePort`; we attribute it to the
link whose endpoint references that port, keyed `link.id || link-${i}`
to match the rest of the server (server.ts / topologies.ts).
Pure; never mutates the input. detectClickSide Determine which side of a node was clicked based on click position. dumpGraph Serialize a graph to authoring YAML, the inverse of `YamlParser.parse()`:
`parse(dumpGraph(g))` is a fixed point over the schema the parser reads.
Hand-rolling this as string concatenation is not safe: any label carrying a
newline (a two-line segment name, say) has to be quoted or the document it
produces is invalid YAML — and a value the writer forgets to emit is simply
gone the next time the text is parsed. Both failure modes are silent. So this
delegates quoting and escaping to js-yaml, and spreads the graph rather than
listing keys: enumerating is what silently drops a field when the model gains
one. Only the three shapes the parser stores differently from how it reads
them are converted (`spec` on nodes and subgraphs, `plug` on link endpoints).
The fixed point holds over the schema the parser reads, which is NARROWER
than the model. Everything else is written to the document — nothing is
dropped here — but is lost the next time that text is parsed:
- graph: `terminations`, `exclusions`, `attachments`
- node: `presence`, `attachments`, `suppressedAttachments`, `entityId`,
`position`, `size`, `termination`, `productId`, `provenance`, `fieldSources`
- link: `via`, `bends`, `rateBps`, `metadata`, `presence`, `provenance`,
`entityId`
- subgraph: `entityId`, `bounds`, `pinPositions`
`presence` and `attachments` are the ones that bite: an `'anchor'` node comes
back as a `'scoop'` (resolve then keeps a device alive that was only meant to
carry identity) and a metrics binding is simply gone. So anything a source
mints beyond the authoring schema — the editor, the resolver, the entity
registry — must not be round-tripped through the YAML pane.
Keep this list honest against the parser. A field the parser stopped reading
(or never read) does not announce itself: `subgraph.identity` was absent here
and unread, so an exported region came back without the key `resolve()`
clusters regions by — one region became two same-labelled boxes with the
members split between them, from a document that looked correct.
`sheets` is the exception that is NOT written: it is a `Map`, which cannot be
expressed here without inventing an authoring form for it (see
`pruneUndefined`).
`lineWidth: -1` disables line folding: folded output re-parses to the same
value, but it makes hand-editing the result confusing. effectiveLinkStandard 英語の追加説明はありません。 effectivePlugCage Resolve the effective plug cage for an endpoint with the canonical priority:
explicit `plug.cage` > module's required cage > port.connectors[0]
(only when the port has a single connector — multi-connector combo
ports require an explicit choice on the link side). Returns undefined
when none are known. effectivePolicyForNode Convenience: compute the effective discovery policy for a node in
the context of a full `NetworkGraph`. Walks the graph 's subgraphs
once into a lookup map, then delegates to `computeEffectivePolicy`.
The resolver, the scheduler, and the API "GET effective policy for
this node" surface all need the same answer; they call this helper. endpointModule 英語の追加説明はありません。 endpointPlugCage 英語の追加説明はありません。 endpointStandard 英語の追加説明はありません。 ensurePorts Walk the graph and ensure every link endpoint references an existing
`NodePort`. Idempotent — graphs that already comply pass through
unchanged (modulo deep-copy). extractHost Host from the common label dialects, in priority order. filterAlertLabels Drop Alertmanager-internal labels (`__name__`, other `__…`). findCollinearOverlaps Find pairs of edges with segments that run on the same track: parallel
(within ~1°), closer than the sum of their half-widths + clearance, and
sharing more than `minSharedLength` of extent. Reports each edge pair
once with its longest shared run. findContainerOverlaps Find pairs of container boxes that overlap where NEITHER is an ancestor of
the other (nesting is legal containment, not interference). findContainmentViolations Find member nodes whose box is not fully inside their container's
bounds (shrunk by `pad` on each side). Unknown member ids are ignored —
membership resolution is the caller's concern. findDetachedTerminals Find wires whose polyline does not terminate ON its ports in from→to
order (port-attachment constraint). Checks both the position (each
terminal within `epsilon` of its port) and the direction contract
(`points[0]` is the FROM port specifically — a reversed but touching
polyline is reported as detached at both ends). Lines with fewer than
two points are skipped: there is no path to check. findEdgeNodePiercing Find wires that run THROUGH a foreign node box (inflated by `inflate`):
any segment crossing one of the box's four borders. A wire may touch its
own endpoints' boxes. Grid-accelerated, exact (same predicate as the old
routed-score inner loop — this IS that loop, extracted so the score and
the constraint check share one definition). findNodeOverlaps Find pairs of node boxes that overlap (optionally requiring `margin`
clear space between boxes). O(n²) — layout-sized inputs only. findPortClutter Find collisions among port boxes, among label boxes, and between a
label and a FOREIGN node box (a label may touch its own node).
O(n²) on layout-sized inputs. flattenObject Flatten an arbitrary upstream record into `DiscoveredMetric[]` for the
plugin "All metrics" passthrough panel.
This is the generic dumper every `HostsCapable` plugin should use instead
of hand-enumerating fields (which is how zabbix ended up coercing every
value to a number and dropping categorical attributes). Walk the object:
- object children join into the metric name with `_`
(`{ a: { b: 1 } }` with prefix `p` → `p_a_b`),
- array-of-primitives emits a `<name>_count`,
- array-of-objects emits a `<name>_count` then expands each element with a
`<key>_index` label,
- null / undefined / empty-string / non-finite leaves are skipped as noise.
Lifted verbatim (behavior-preserving) from the aruba-instant-on plugin,
which had the only correct generic implementation. formatReachMeters Format a meters value for UI display (1000+ → km). getBandwidthWidth Map a bandwidth label/number to the calibrated stroke width. getDeviceIcon Get SVG icon content for a device type getLinkWidth Compute the visual line width for a link.
Single source of truth — used by layout, routing, and rendering. getLinkWidthForMode Visual line width for a link under a width mode. Same precedence as
`getLinkWidth` (explicit style > bandwidth > type > default). Because a
core `Link` is one physical link, this IS the per-strand width — a LAG
renders as N parallel links each at its own width, never as one merged
stroke (v3 "railway discipline": no two services share a drawn line). getNodeId Helper to get node ID from endpoint. Kept as a tiny accessor so callers
read intent ("the link's source node") rather than reaching into shape. getStandardSpec 英語の追加説明はありません。 getThemeFromCSS Get theme from CSS variables groupCableVariants Group cable variants by `cableKind` for sectioned `<optgroup>` rendering. groupCouplingPairs Union-find grouping of coupling pairs into redundancy groups (an N-member
stack is a chain of pair links). Generic over ids so both renderers can
feed their edge shapes in. `kind` of the group = the first pair's kind. groupStandards Group a list of `StandardOption`s by their `group` for sectioned dropdowns. hasAlertsCapability 英語の追加説明はありません。 hasAutoscanCapability 英語の追加説明はありません。 hasConfigOptions Duck-type: can this plugin supply dynamic candidates for `optionsSource` fields? hasConnectionInfo Duck-type: does this plugin expose derived, display-only connection info? hasHostsCapability 英語の追加説明はありません。 hasMetricsCapability 英語の追加説明はありません。 hasNativeApi Duck-type check: does this plugin expose a native-API passthrough?
Intentionally not bound to a `DataSourceCapability` literal — this is a
developer-only escape hatch, not a product feature, so it stays off the
advertised capability list. hasTopologyCapability 英語の追加説明はありません。 interfaceMatchScore Score how well two normalized interface names match (0–1): same canonical
prefix, then port numbers compared right-to-left (rightmost = most specific). interfaceNamesMatch Whether two interface names denote the same physical port. Same canonical
prefix with aligning numbers (score ≥ 0.5), OR — for cross-vocabulary cases
like TTDB's speed-code `hg` vs Juniper `et-` where prefixes differ but the
port number is identical — the full number sequence matches. isExcluded True when the node should NOT be auto-touched by the scheduler or
by any source's discovery pass — convenience predicate that hides
the mode comparison from callers that just need a yes/no answer. isExportLink Check if a link is a virtual export connector link isExportNode Check if a node is a virtual export connector isPluggableConnector 英語の追加説明はありません。 isPoeCapableConnector 英語の追加説明はありません。 isPortLinked Whether the given port already appears as an endpoint of any link.
A physical port models one cable termination, so it can host at most
one link at a time. Callers use this to reject attempts to wire a
second link onto an already-connected port — `linkExists` only
catches exact-duplicate links, which isn't enough for the "1 port =
1 link" invariant. isSecretProp A field is a write-only secret if it declares `secret: true`. `format:
'password'` is honoured too so external plugins that predate the flag keep
working; new schemas should set `secret: true`. issuesForTarget Filter issues whose target points at a specific field. Used by the UI. keyHash Stable string form of a key for use as a Map key. layoutComposite 英語の追加説明はありません。 linkExists Check if a link already exists between two ports. linkSpeedBps Resolve a link's nominal speed (bits/sec). Reads per-endpoint module
standards (the canonical source) and falls back to runtime `rateBps`
when neither end has a module set. For symmetric links both endpoints
return the same speed; for asymmetric links (BiDi etc.) we pick the
lower of the two (conservative for utilization math). mapAlertmanagerSeverity 英語の追加説明はありません。 mapWithConcurrency Run `fn` over `items` with at most `limit` calls in flight at once,
preserving input order in the result array.
Replaces the two failure modes the audit found: unbounded `Promise.all`
fan-out (network-scan would open hundreds of SNMP sockets at once) and
fully sequential `await`-in-a-loop polling (zabbix walked hosts one by
one). A rejected `fn` rejects the whole call (like `Promise.all`); a
caller wanting partial results should catch inside `fn`. mediumFromGrade Derive the cable medium kind from a `CableGrade`. Twisted-pair
categories map to twisted-pair, OM3/4/5 → multi-mode fiber, OS1/2 →
single-mode fiber, DAC and AOC are their own mediums. mediumFromStandard Derive the cable medium implied by an Ethernet standard. Resolves
the standard via `STANDARD_SPECS` and maps `cableKind` + `fiberMode`
onto the unified `CableMedium` enum. mergeTheme Merge theme with overrides metricsBindingOf The metrics-binding attachment on an element, if any. When `activeSourceIds`
is given, only a binding whose `sourceId` is active counts — so a binding left
behind by a detached/removed metrics source stops driving the mapping. migratePortShape Backwards-compat shim for saved files: an older NodePort serialized
with `cage: PortConnector` (or `cage: 'combo'`) is normalized into
the modern `connectors: PortConnector[]` shape on read. Combo expands
to ['rj45', 'sfp'] as a best-effort default; users can refine from
the editor afterwards. missingCapabilityMethods Declared capabilities whose required method is missing on a constructed
instance, formatted `"cap → method()"`. Empty array = compliant. Unknown
(open) capabilities are skipped. The registry calls this once at first
instantiate (decision 7) to catch a plugin that advertises a capability it
doesn't actually implement (C6). moveNode 英語の追加説明はありません。 movePort Move a port to the nearest edge of its node based on cursor position.
Changes the port's side and redistributes all ports.
Returns null if the side didn't change. moveSubgraph Move an entire subgraph (bounds + all contents) by delta from its current position.
Resolves sibling collisions after the move. newId Generate a fresh unique ID for the given entity kind.
Collision probability for 10-char nanoid is negligible for editor-scale
workloads (~trillions of IDs before 1% collision chance). nodeIdentityKeys Enumerate Node identity keys in priority order. The first match
wins during cluster lookup. Caller should also bind *every* key
to the resulting cluster after a match so subsequent observations
collapse correctly even if they only carry a weaker key. nodeIdentityQuality Coarse identity quality — surfaced in UI to warn users which
elements may detach from their metrics/observations across reboots.
Node: `stable` if chassisId + (mgmtIp or sysName), `weak` if any
single primary key, `unbound` otherwise.
Port: `stable` if ifName + (mac or ifIndex), `weak` if any single
key, `unbound` otherwise. nodesOverlap Check if two centre-based rectangles overlap with a gap.
Free function for callers that want to do their own
collision math; the engine's `tryPlace` is preferred for
full placement validation. normalizeInterfaceName Normalize an interface name to `{ prefix, numbers, sub }`. The numeric part is
split on `/`, `-`, or `:` so TTDB's dash form ("hg-0-0-0" → [0,0,0]) lines up
with the slash form ("hg/0/0/0" → [0,0,0]). normalizeMacKey Canonical spelling for a MAC-shaped identity key: lowercase, colon-separated.
Sources disagree on how to write the same wire address. Huawei NCE returns
`50-04-01-01-D5-50` in its device list and `CC:D8:1F:9F:D4:AB` in its LLDP
table; an SNMP walk of the very same switch yields `cc:d8:1f:9f:d4:ab`; Cisco
gear writes `ccd8.1f9f.d4ab`. Identity keys are matched as exact strings, so
without one canonical spelling a device arrives as two entities that never
merge — the failure is silent, which is what makes it worth normalizing here
rather than in each plugin.
Anything that is not twelve hex digits once separators are stripped is
returned untouched: `chassisId` is only sometimes a MAC (LLDP also permits
interface names and network addresses) and must survive as written. normalizePortConnector 英語の追加説明はありません。 paperSizeToPixels Convert paper size to pixels at given DPI parseAlertmanagerAlerts Parse an Alertmanager response into core `Alert[]`, applying the standard
active/timeRange and minSeverity filters.
- Active alerts are always kept; resolved alerts are dropped when
`activeOnly`, otherwise dropped once older than `timeRange` (default 1h).
- Unparseable `startsAt` falls back to `now`; missing/unparseable `endsAt`
yields `undefined` (no bogus epoch-0 end time). parseWithMaps 英語の追加説明はありません。 placeNode **Geometric** placement for a single unpositioned node: find the
point nearest `initial` that doesn't overlap any existing node or
subgraph. The graph's link structure is deliberately ignored — this
is the primitive for "drop the node exactly where the user clicked",
"paste at cursor", "convert BOM item to diagram node at the canvas
edge", i.e. user-driven placement where the surrounding topology
should not influence the outcome.
For **structural** placement (re-layout based on link flow, pin a
set of nodes, arrange a selection), use `layoutNetwork` with its
`fixed` / `hints` options instead. The two APIs stay separate
because their intents differ: `placeNode` is O(existing obstacles)
geometry, `layoutNetwork` is a full Sugiyama run. placePorts Compose the three phases: decide sides → order each side → compute
absolute coordinates → emit `ResolvedPort`s keyed by `nodeId:portId`.
Port sides are re-seated from final geometry (see
reseatPortsByGeometry) so wires exit toward their peer
regardless of how the upstream/downstream tree was inferred. Ports
are positioned along each side by distributePortsAlongSide
(peer-aligned), with computePortPosition's even spread as the
fallback. plugFromCage Build a cage-only plug — the user picked a form factor without a module yet. plugFromStandard Build a plug from a chosen module standard. The plug carries only the
`module` — `cage` is intentionally omitted because it's derivable from
`module.standard` via `STANDARD_SPECS[std].cage`. Returns `undefined`
if the standard is unknown. plugProfileForStandard Resolve a standard to its plug profile (for prefilling the plug select). plugProfilesForConnectors Plug profiles compatible with the given port connectors. Empty
arrays are permissive (return all plugs); multi-connector combo
ports return the union of compatible plugs. portBox Axis-aligned box of the port marker itself. portIdentityKeys Enumerate Port identity keys in priority order. Port matching
happens *within* a parent node cluster — the same `ifName` on a
different chassis is a different port. The caller is responsible
for that scoping; this list is just the per-port priority order. portIdentityQuality 英語の追加説明はありません。 portLabelBox Axis-aligned box of the port's label, or undefined when the port has
no label. Mirrors the renderer:
- vertical (composite top/bottom): the label runs along the wire,
away from the node face, in a 12px-wide strip.
- horizontal: classic placement per side (above / below / beside). portLabelLength Estimated label box length along the reading direction. portLabelReach Reach of a port's label measured from the node face outward, along
the wire (vertical labels) — how much corridor the label needs
between this row and the next. Horizontal labels reach PORT_LABEL_H. reachForLink Effective reach in meters for a link, accounting for the cable grade.
Falls back to the standard's `maxReach_m` when the grade isn't set or
isn't in the registry's per-grade table. rebalanceSubgraphs Rebalance the entire layout after any mutation.
Uniform algorithm:
1. Recompute subgraph bounds (bottom-up, deepest first)
2. Resolve subgraph vs subgraph sibling collisions
3. Resolve subgraph vs free node collisions (push nodes away) removePort Remove a port and redistribute remaining ports on the same node.
Also removes any links that reference this port.
Returns updated nodes, ports, and links. resolve Resolve the project's own (intrinsic) NetworkGraph against any number of
source snapshots into a single graph whose every entity carries
`provenance`.
Model: **all sources are equal, priority-ordered contributions.** The
intrinsic (project-owned) graph is just the top-priority contribution;
observed snapshots carry their own priority (mirroring
`topology_data_sources.priority`). resolve clusters contributions by
identity (any-key match — orthogonal to priority) and then, **per
field**, the highest-priority contribution that actually holds a value
wins (`priority desc, capturedAt desc`). A field nobody holds is
omitted. This is the "Git-like" merge: an edit that only renamed a node
keeps the observed ports/community flowing through untouched.
There is intentionally NO `=== 'intrinsic'` special-casing in the field
merge — "the project's edits win" falls out of "intrinsic has the highest
priority". The reserved id `'intrinsic'` survives only as that
contribution's source *label*, so the UI can tell a project-set value from
an observed one (per-field `fieldSources`, per-attachment `provenance`). It
is ownership (intrinsic vs external), NOT a human-vs-machine layer.
See `apps/server/docs/design/topology-source-priority-merge.md`. resolveBandwidthBps Parse a bandwidth string ("10G", "2.5Gbps", "500M") or raw bps number
into bits/sec. Pure utility — used by plugin configs that accept
user-typed bandwidth values; not tied to Link semantics. resolveIcon Resolve the icon to render for a given spec. Returns the explicit
`spec.icon` if any; otherwise the bundled device-type fallback;
otherwise null. resolveLayout Convert a legacy LayoutResult to a ResolvedLayout.
Port positions are converted from center-relative to absolute. resolveNodePosition Resolve a node's position against all other entities.
Wrapper around `resolvePosition` for the legacy id-based
API. resolveNodeSize Resolve a node's display size — returns the node's own
`size` if set, otherwise asks the engine for its body size.
Pass `engine` to share its TextMeasurer cache with other
queries. Without one, a process-wide default engine is
created lazily; this is fine for one-off helpers but not
ideal for hot loops where explicit control matters. resolvePosition Resolve position of any rectangle against all obstacles
(nodes + subgraphs). Delegates to the engine's geometric
solver so editor / renderer / layout all use the same
collision rules. routeEdges Produce a `ResolvedEdge` for every link whose endpoints resolve to
known ports. Links pointing at a missing port are dropped (matches
the previous behaviour of libavoid-router).
The function returns a Promise for backwards compatibility with
the old WASM-backed router — every existing caller already awaits
the result, and async-of-sync incurs zero cost.
`nodes` is accepted but unused so the signature mirrors the
historical libavoid-router API. Bezier edges read positions off
`ports` directly via each `ResolvedPort.absolutePosition`. scoreRoutedEdges Score actually-routed geometry (no straight-line proxies). searchCompositeLayout Run the search: parameter multi-start → congestion pass → pair flips.
Total evaluations stay within `maxEvaluations` (default 16); the
result is always the best ROUTED variant seen. segmentsIntersect Shared exact segment-intersection predicate (strict crossing). severityAtLeast True when `severity` is at least as severe as `min`. severityRank Rank of a severity (unknown → `info`). shouldUseComposite 英語の追加説明はありません。 specDeviceType Extract DeviceType from a spec (hardware and compute only). stampObserved Return a copy of `node` stamped with observation provenance, identity, and
sync metadata. Never mutates the input (callers build node lists with
`.map(stampObserved…)`). Existing identity/metadata are preserved and only
overlaid with the supplied values. standardsForConnectors Standards available given the connectors on each port. Used by the
editor's cascading "Standard" picker so the dropdown only offers
links that physically fit. Empty arrays are treated permissively —
we'd rather show too many than none.
For combo ports (multiple connectors), this returns the union: any
standard that fits at least one connector on each side qualifies.
Returned as one flat list; group via `option.group` if the UI wants
to split into sections. stringifyWithMaps 英語の追加説明はありません。 symmetricPlug Produce a symmetric plug spec for a link — both endpoints get the same
plug+module. Used by editor flows that default to symmetric links. unresolveLayout Convert a ResolvedLayout back to a legacy LayoutResult.
Used for backward compatibility with existing renderers. validateAgainstSchema 英語の追加説明はありません。 validateLinkCompatibility Validate a link against its endpoints, ports, and cable. Runs every
registered endpoint-level and link-level check; collects all issues
the UI / consumers can route to inline markers via `issuesForTarget`. validateTopologyIdentityContract Check whether `graph` satisfies the topology identity contract.
Returns arrays of violating node/port ids. Both arrays empty → contract met. verifyLayoutConstraints Verify a ResolvedLayout against the registry. Every check derives its
parameters from the specs above — no second source of truth. verifySemanticLayout 英語の追加説明はありません。