gitnexus 1.6.11-rc.8 → 1.6.11

package/dist/core/ingestion/frameworks/spring/destinations.d.ts

@@ -0,0 +1,539 @@
+import type { SpringArgumentFact } from './argument-facts.js';
+import type { SpringMessageProducerTemplate } from './message-producers.js';
+/**
+ * Resolution of Spring async messaging DESTINATIONS — the broker address a
+ * `@KafkaListener` reads from or a `kafkaTemplate.send(...)` writes to.
+ *
+ * The capture layer records the destination argument exactly as written and
+ * resolves nothing (see `argument-facts.ts`). This module is the other half:
+ * it decides WHICH argument names the destination, then walks a four-step
+ * cascade to turn that argument's source text into an address. It is pure —
+ * no graph, no filesystem, no parser — so every rule below is unit-testable
+ * against a string, and `pipeline-phases/spring-destinations.ts` is left with
+ * only node and edge emission.
+ *
+ * ── THE INVARIANT THIS MODULE EXISTS TO PROTECT ──────────────────────────
+ *
+ * An address that could NOT be resolved must never become a shared identity.
+ * Two unrelated services that each merely write
+ *
+ *     @KafkaListener(topics = "${app.topic}")
+ *
+ * have said nothing about each other. If the graph keyed a destination node on
+ * that placeholder text, they would land on one node and READ AS CONNECTED —
+ * and a false edge is worse than a missing one, because a missing edge is
+ * visible as a gap while a false one enters reports as a fact.
+ *
+ * So this module never returns a placeholder, a constant name, or any other
+ * unresolved spelling as an `address`. An unresolved candidate comes back as
+ * `{ kind: 'unresolved', reason }` with no address at all, and the phase keys
+ * such a node by its SOURCE LOCATION. A status flag would not have been
+ * enough: the two services would still share whatever key the node was minted
+ * from. Only withholding the key prevents the join.
+ *
+ * ── REFUSAL IS DATA ──────────────────────────────────────────────────────
+ *
+ * Every path that declines to produce an address records WHY, from a closed
+ * set ({@link SpringDestinationRefusal}). The measure of this feature is the
+ * unresolved fraction, so a silent `continue` would hide precisely the number
+ * that says whether it works.
+ */
+/**
+ * Broker family behind a destination, as far as the syntax can attest.
+ *
+ * Part of the `Destination` node IDENTITY, not merely a label on it: the phase
+ * keys a resolved node by `(broker, address)` via the framework-neutral
+ * `ingestion/destination-key.ts`, so two brokers claiming one address are two
+ * ordinary nodes. Adding or renaming a member here therefore re-keys every node
+ * it applies to, which a full re-index absorbs and an incremental one does not
+ * — the destination layer is delete-alled and rebuilt graph-wide on every
+ * incremental writeback for exactly this class of reason.
+ *
+ * A member is only added when the SYNTAX attests to it. A guess here becomes a
+ * guess in the identity, and the cost of a wrong one is a real pair split in
+ * two (see `destinationNodeKey` for why that cost is nonetheless the cheaper
+ * of the two failures available).
+ */
+export type SpringDestinationBroker = 'kafka' | 'rabbit' | 'jms' | 'pulsar' | 'sqs' | 'stream' | 'integration';
+/**
+ * Why a candidate produced no address. Closed set: each member is a distinct,
+ * countable diagnosis, and no path may decline without naming one.
+ *
+ * Members are split rather than merged wherever the two causes are different
+ * FACTS about the repository. The unresolved fraction is only useful if its
+ * breakdown says what to go and fix, and a bucket that means "either the
+ * capture could not read this or the source really did write it that way"
+ * answers neither question.
+ */
+export type SpringDestinationRefusal = 
+/** The annotation is a recognized listener but its arguments were never read
+ *  — a CAPTURE limitation, not a statement about the source. */
+'annotation-arguments-unavailable'
+/** The annotation's argument list was read and it was EMPTY: `@KafkaListener`
+ *  with no elements at all. A real source-level gap, and deliberately not the
+ *  same bucket as `annotation-arguments-unavailable` — see
+ *  `SpringNonHttpHandlerAnnotationFact.args`, which keeps absent and `[]`
+ *  apart precisely so a consumer of the fact does not have to guess. */
+ | 'annotation-arguments-empty'
+/** Recognized listener, argument list present, no element names a destination. */
+ | 'no-destination-argument'
+/** `@KafkaListeners({@KafkaListener(...), ...})` and its siblings. The
+ *  container's single argument is a list of NESTED annotations, and capture
+ *  does not descend into them, so their destinations are unreadable here.
+ *  Recorded rather than skipped: a repository using repeated-listener
+ *  containers loses real destinations, and that has to show up in the count
+ *  instead of looking like a repository with no listeners. */
+ | 'repeated-listener-container'
+/** `@KafkaListener(topicPattern = ...)` — a regex over topics, not an address. */
+ | 'topic-pattern'
+/** A destination form this module deliberately does not read, e.g.
+ *  `@RabbitListener(bindings = @QueueBinding(...))` or `topicPartitions`. */
+ | 'unsupported-annotation-argument'
+/** A Kotlin trailing-lambda call: the publish has no argument list at all. */
+ | 'producer-arguments-unavailable'
+/** The call's arity matches none of the overloads that carry a destination. */
+ | 'producer-arity-unrecognized'
+/** The call used NAMED arguments and none of them names a destination
+ *  parameter this module knows. Selecting by position instead would read
+ *  whatever the author happened to write first — see
+ *  {@link selectProducerDestinationArguments}. */
+ | 'producer-named-argument-unrecognized'
+/** `rabbitTemplate.convertAndSend(message)` — default exchange, empty routing
+ *  key. There is no address in the source to record. */
+ | 'rabbit-default-exchange'
+/** The argument in the destination position is not shaped like an address
+ *  (not a string literal, not a constant reference) — most often because the
+ *  overload actually taken has the payload there. */
+ | 'producer-argument-not-address-shaped'
+/** Two overloads fit the call, they disagree about which slot is the address,
+ *  and the argument is spelled the same way under both readings. The
+ *  archetype is `convertAndSend("orders.rk", "body", correlationData)`: it is
+ *  `(exchange, routingKey, message)` with the address `"body"`, or
+ *  `(routingKey, message, correlationData)` with the address `"orders.rk"`
+ *  and `"body"` as a String PAYLOAD. Both are real overloads spelled
+ *  (String, String, ref).
+ *
+ *  Distinct from `producer-argument-not-address-shaped`, which says the slot
+ *  cannot hold an address at all. This one says it can, twice, and the module
+ *  will not pick — a payload published as an address joins a consumer of a
+ *  queue that happens to be named after the payload's text. */
+ | 'ambiguous-producer-overload'
+/** `topics = {}` / `topics = []` / `arrayOf()`. */
+ | 'empty-destination-list'
+/** The element is an expression this module will not evaluate — a
+ *  concatenation, a call, a ternary. */
+ | 'not-a-literal-or-constant'
+/** A constant reference no constant resolver could fold to a string. */
+ | 'unresolved-constant'
+/** `#{...}` — a SpEL expression, evaluated by the container against beans and
+ *  the environment at RUNTIME. `#{@kafkaProps.ordersTopic}` is the archetypal
+ *  unresolvable address: nothing in the source says what it evaluates to, and
+ *  two services that merely wrote the same expression have said nothing about
+ *  each other. */
+ | 'spel-expression'
+/** An unescaped `$` interpolation in a language whose string literals
+ *  interpolate. In Kotlin `"orders-$env"` and `"orders-${env}"` are STRING
+ *  TEMPLATES evaluated at runtime, not addresses and not Spring placeholders
+ *  — the escaped `"\${app.topic}"` is how a Spring placeholder has to be
+ *  written there. Java does not interpolate, so `$` is an ordinary character
+ *  and this never fires for it. */
+ | 'unescaped-interpolation'
+/** `${key}` with no default. The KEY is recorded; the VALUE is deliberately
+ *  absent from the graph (config values may hold credentials — see the header
+ *  of `pipeline-phases/spring-config.ts`), so this can never resolve here. */
+ | 'unresolved-config-key'
+/** `${key:default}`. The default IS written in the source, and it is kept on
+ *  the node — but it is not an IDENTITY. It holds only while the key is not
+ *  overridden in configuration, and configuration VALUES are deliberately
+ *  absent from this graph, so the code cannot know whether it holds. Keying
+ *  on it merges every service that copy-pasted the same fallback: `${a:events}`
+ *  and `${b:events}` are two different addresses that happen to share a
+ *  default. Both the key and the default text survive as properties, so the
+ *  case stays countable and distinguishable from a bare `${key}`. */
+ | 'overridable-config-default'
+/** `${}` — a placeholder that names no key. There is nothing to record and
+ *  nothing to look up; kept separate so an empty key never reaches the
+ *  `Property` lookup as if it were a real one. */
+ | 'empty-config-key'
+/** A string literal that is empty or nothing but whitespace. An empty address
+ *  addresses nothing, and letting it through would give every such site one
+ *  shared `''` identity — the same false join the placeholder rule prevents. */
+ | 'empty-literal-address'
+/** A constant reference that folded to an empty or whitespace-only string.
+ *  Same outcome as `empty-literal-address`, different repository fact: there
+ *  the source wrote `""`, here a constant declaration did. */
+ | 'empty-constant-address';
+/**
+ * How an address was arrived at, kept on the node for provenance.
+ *
+ * There is deliberately no `config-default` member. A `${key:default}` does not
+ * resolve — see `overridable-config-default` — so no address can be reached
+ * that way.
+ */
+export type SpringDestinationVia = 'literal' | 'constant' | 'specification';
+export type SpringDestinationRole = 'consumer' | 'producer';
+/**
+ * One argument element that has been ACCEPTED as naming a destination, before
+ * any attempt to resolve it. An array-valued argument yields one candidate per
+ * element: `topics = ["a", "b"]` really is two destinations, and each gets its
+ * own node and its own edge (see the phase for why no group node is minted).
+ */
+export interface SpringDestinationCandidate {
+    readonly role: SpringDestinationRole;
+    /** Annotation simple name (`KafkaListener`) or producer template (`kafka`). */
+    readonly source: string;
+    readonly broker: SpringDestinationBroker;
+    /** Index of the argument this element came from, in source order. */
+    readonly argIndex: number;
+    /** Argument name when the call/annotation named it (`topics`, `queues`). */
+    readonly argName?: string;
+    /** Index within an array-valued argument; `0` for a scalar. */
+    readonly elementIndex: number;
+    /** The element's source text, exactly as captured. */
+    readonly rawText: string;
+    /** Companion provenance that is not itself an address — currently only the
+     *  Rabbit exchange that accompanies a routing key. */
+    readonly exchange?: string;
+}
+/** A candidate that was declined before resolution was even attempted. */
+export interface SpringDestinationRefusalRecord {
+    readonly role: SpringDestinationRole;
+    readonly source: string;
+    readonly broker: SpringDestinationBroker;
+    readonly reason: SpringDestinationRefusal;
+    /** Source text that provoked the refusal, when there was one. */
+    readonly rawText?: string;
+    readonly argIndex?: number;
+    readonly argName?: string;
+}
+export interface SpringDestinationSelection {
+    readonly candidates: readonly SpringDestinationCandidate[];
+    readonly refusals: readonly SpringDestinationRefusalRecord[];
+}
+export type SpringDestinationResolution = {
+    readonly kind: 'resolved';
+    readonly address: string;
+    readonly via: SpringDestinationVia;
+} | {
+    readonly kind: 'unresolved';
+    readonly reason: SpringDestinationRefusal;
+    /** Configuration key named by an unresolvable `${...}` placeholder. Lets
+     *  the phase link the node to the `Property` nodes for that key without
+     *  ever learning the key's value. */
+    readonly configKey?: string;
+    /** Default text of a `${key:default}`, exactly as the source wrote it.
+     *  Kept as PROVENANCE only — it is never an address and never a key, for
+     *  the reason `overridable-config-default` gives. */
+    readonly configDefault?: string;
+};
+/**
+ * The cascade's pluggable steps plus the one language capability it needs.
+ *
+ * The steps are supplied by the phase, which owns the language-specific
+ * machinery; keeping them as callbacks is what lets this module stay
+ * language-neutral and testable with a plain map.
+ */
+export interface SpringDestinationResolvers {
+    /**
+     * Whether the owning language INTERPOLATES string literals — Kotlin does,
+     * Java does not. A capability, deliberately not a language name: shared
+     * ingestion code may not branch on a language (see AGENTS.md), and the
+     * capability is also the thing that actually matters. Supplied alongside
+     * `getSpringMessagingFacts` by the provider and threaded in by the phase.
+     *
+     * When true, an unescaped `$` inside a literal is a runtime template and the
+     * candidate is refused. When false (the default) `$` is an ordinary
+     * character and `"${app.topic}"` is a Spring placeholder.
+     */
+    readonly interpolatesStringLiterals?: boolean;
+    /**
+     * Step 2 — fold a constant reference (`Topics.ORDERS`, `ORDERS`) to its
+     * string value, or `null` when it cannot be folded. Backed by
+     * `resolveJavaConstant` / `resolveKotlinConstant`.
+     */
+    readonly constant?: (name: string) => string | null;
+    /**
+     * Step 4 — SEAM, DELIBERATELY NOT IMPLEMENTED.
+     *
+     * Some destinations are named nowhere in the source: the address lives in a
+     * published API specification (AsyncAPI / springwolf) that the service
+     * generates, and the code only names a binding. Resolving those means reading
+     * an artifact that is not a source file, deciding which specification belongs
+     * to which module, and trusting a generated document — a different problem
+     * from the three syntactic steps above, with a different failure mode.
+     *
+     * The hook exists so that work has a defined place to land and so the cascade
+     * order is fixed now rather than renegotiated later. Nothing supplies it
+     * today, so step 4 is a no-op and such destinations stay unresolved with the
+     * reason the earlier step recorded.
+     *
+     * ── STILL UNSUPPLIED, AND NOW FOR A REASON RATHER THAN FOR WANT OF A READER ──
+     *
+     * `core/ingestion/asyncapi/document.ts` reads AsyncAPI 3.x documents, and
+     * `pipeline-phases/spring-destinations.ts` emits what they state as
+     * destinations of their own. It does NOT feed this hook, and the gap is a
+     * decision:
+     *
+     * A document names addresses; it does not name the method that uses one. To
+     * hand an address to THIS candidate, something has to choose which of the
+     * document's operations belongs to it. Partitioning by (broker, action) is
+     * the only division both sides agree on, and it is a weak one: a service with
+     * several listeners on one broker puts them all in one bucket. Any bucket
+     * holding more than one operation forces a heuristic, and a wrong heuristic
+     * puts a REAL address on a joining node under the wrong site — a false
+     * connection wearing the clothes of a resolved one, which is the exact
+     * outcome this module's keying rule exists to prevent. Only a bucket of size
+     * one is a fact rather than a guess.
+     *
+     * Two things would change that, and neither is a heuristic: a document whose
+     * operations carry the implementing symbol, or a configuration source that
+     * answers the `${key}` this candidate already recorded. The second is the
+     * stronger of the two — a key-to-value lookup is exact where a document match
+     * is a guess — and it wants its own resolver rather than this one, because
+     * what it needs is the placeholder key, not the candidate.
+     */
+    readonly specification?: (candidate: SpringDestinationCandidate) => string | null;
+}
+/**
+ * Choose the destination-bearing arguments of one listener annotation.
+ *
+ * Returns `null` when the annotation is not a broker listener at all — that is
+ * not a refusal, there was nothing to refuse. A recognized annotation always
+ * returns a selection, even when every path in it declined, so the caller can
+ * count what was seen against what resolved.
+ */
+export declare function selectConsumerDestinationArguments(annotationName: string, args: readonly SpringArgumentFact[] | undefined): SpringDestinationSelection | null;
+/**
+ * Choose the destination-bearing arguments of one messaging-template publish.
+ *
+ * A NAME beats a position, arity decides where it can decide, and shape decides
+ * where it cannot.
+ *
+ * When any argument is passed by name, {@link PRODUCER_DESTINATION_PARAMETERS}
+ * decides — position is not consulted at all, because a named argument list
+ * need not be in parameter order. When the slot this module would have read
+ * positionally is itself named with something it does not recognize, that is a
+ * contradiction and the publish is refused rather than read.
+ *
+ * `KafkaTemplate.send` and `StreamBridge.send` put the destination first in
+ * every multi-argument positional overload they have, so once such a call has
+ * two or more arguments its slot 0 is the destination and nothing further needs
+ * deciding. Those slots use the PERMISSIVE gate ({@link isAddressShaped}): a
+ * bare identifier is let through to the cascade, which refuses it by name if no
+ * constant folds. That keeps `unresolved-constant` — a thing we tried to
+ * resolve — distinct from `producer-argument-not-address-shaped`, a thing we
+ * declined to read at all.
+ *
+ * The `convertAndSend` families are different. Both admit trailing
+ * `MessagePostProcessor` and `CorrelationData` parameters, and arity does not
+ * separate the overloads in EITHER direction:
+ *
+ *   jms    (destination, message)                2  vs (message, postProcessor)          2
+ *   rabbit (routingKey, message)                 2  vs (message, postProcessor)          2
+ *   rabbit (exchange, routingKey, message)       3  vs (routingKey, message, pp)         3
+ *                                                   vs (routingKey, message, correlation) 3
+ *   rabbit (exchange, routingKey, message, pp)   4  vs (routingKey, message, pp, corr)   4
+ *
+ * So the tie is broken by the STRICT gate ({@link isConfidentAddressShape}) — a
+ * string literal, a qualified reference, or a screaming-snake constant, all of
+ * which a payload variable is not. A lowercase bare identifier is NOT confident
+ * evidence, so `convertAndSend(topic, payload)` is refused rather than read:
+ * the same spelling is how a payload variable looks, and nothing in the syntax
+ * separates them. That refusal is the deliberate cost. A refusal is counted and
+ * recoverable; a wrong address enters reports as a fact.
+ *
+ * There is NO positional fallback at rabbit arity 3+. An earlier revision fell
+ * back to accepting slot 0 when slot 1 was not confident, which turned the
+ * ordinary `convertAndSend(EXCHANGE, routingKey, event)` — routing key in a
+ * variable — into a destination whose address was the EXCHANGE NAME. That is
+ * the worst possible outcome: an address that looks entirely plausible and can
+ * join a `@RabbitListener(queues = "orders")` that has nothing to do with it.
+ *
+ * ── THE ONE AMBIGUITY, REFUSED RATHER THAN GUESSED ───────────────────────
+ *
+ * `convertAndSend("orders.rk", "body", correlationData)` fits two overloads at
+ * once and they disagree about which slot is the address:
+ *
+ *     (exchange, routingKey, message)          → the address is `"body"`
+ *     (routingKey, message, correlationData)   → the address is `"orders.rk"`
+ *
+ * Both are real, both are spelled (String, String, ref), and no rule over the
+ * syntax separates them. Picking either one publishes the OTHER reading's
+ * payload as an address, where a consumer of a queue named after that text
+ * joins a publisher that never wrote to it. So neither is picked: the call is
+ * refused as `ambiguous-producer-overload` and yields no candidate and no edge.
+ *
+ * The refusal is narrow on purpose, because over-refusing here costs the
+ * ordinary case, and a suppression that eats correct results is the more
+ * expensive mistake. It fires ONLY on a STRING LITERAL in slot 1, at the
+ * arities where a competing overload exists:
+ *
+ *   - A literal is no evidence at all. An address and a payload are BOTH
+ *     ordinarily written as literals, so the spelling distinguishes nothing.
+ *   - A CONSTANT or QUALIFIED reference is evidence, which is the whole premise
+ *     of {@link isConfidentAddressShape}: `ORDERS_ROUTING_KEY` and
+ *     `Topics.ORDERS_KEY` are how a configured NAME is written, not how a
+ *     payload computed at the call site is. Those keep resolving.
+ *   - Arity 5 has no competing overload at all —
+ *     `(exchange, routingKey, message, pp, correlationData)` is the only
+ *     five-argument form — so slot 1 there is the routing key whatever it is
+ *     spelled like, and the refusal must not reach it.
+ *   - A NAMED argument settles the reading outright, and the name-beats-position
+ *     pre-pass above has already returned by then.
+ */
+export declare function selectProducerDestinationArguments(fact: {
+    readonly template: SpringMessageProducerTemplate;
+    readonly methodName: string;
+    readonly args?: readonly SpringArgumentFact[];
+}): SpringDestinationSelection;
+/**
+ * Split an array-valued destination argument into its elements.
+ *
+ * Both languages hand this module ONE unsplit string per argument: capture
+ * records an argument's source text, and `topics = {"a", "b"}` is a single
+ * argument whose text happens to be a list. So the list is parsed here, in the
+ * three spellings the two languages use — Java `{…}`, Kotlin `[…]`, and Kotlin
+ * `arrayOf(…)`.
+ *
+ * Anything else comes back as a single element, unchanged: a scalar argument,
+ * and equally an expression that merely starts with a brace. The split tracks
+ * nesting and string literals, so a comma inside a literal or inside a nested
+ * call does not split the list.
+ *
+ * Returns `[]` for an empty list, which the caller must distinguish from a
+ * one-element list — `topics = {}` names no destination at all.
+ */
+export declare function splitSpringDestinationList(text: string): readonly string[];
+/**
+ * Unquote a string literal to its value, or `null` when the text is not a
+ * single literal.
+ *
+ * Escapes are undone only for the sequences that can appear inside a
+ * destination: `\"`, `\\`, and Kotlin's `\$`. That last one matters more than it
+ * looks — a Spring placeholder written in Kotlin MUST escape the dollar
+ * (`"\${app.topic}"`) or the compiler reads it as a string template, so without
+ * undoing it every Kotlin placeholder would fail the `${` test below and be
+ * misfiled as a plain literal address named `\${app.topic}`.
+ *
+ * The unescaping is also why {@link hasUnescapedStringInterpolation} has to run
+ * against the RAW text: once `\$` has become `$`, the escaped placeholder and
+ * the runtime template are the same string.
+ */
+export declare function parseSpringStringLiteral(text: string): string | null;
+/**
+ * Whether a string literal contains an UNESCAPED interpolation, for a language
+ * whose literals interpolate.
+ *
+ * Only meaningful for such a language; Java never calls it. In Kotlin:
+ *
+ *     "orders-$env"        template — the value is decided at runtime
+ *     "orders-${env}"      template — NOT a Spring placeholder
+ *     "\${app.topic}"      escaped  — this is how a Spring placeholder is written
+ *     """orders-$env"""    template — raw strings interpolate and cannot escape
+ *
+ * Reads the RAW literal text on purpose: {@link parseSpringStringLiteral}
+ * resolves `\$` to `$`, after which the second and third rows above are the
+ * same string and the distinction is gone. A raw (`"""`) literal has no
+ * backslash escapes at all — `${'$'}` is the only way to write a dollar there —
+ * so every `$` in one is an interpolation.
+ */
+export declare function hasUnescapedStringInterpolation(text: string): boolean;
+/**
+ * PERMISSIVE gate — true when the text could name an address: a string literal,
+ * or any reference a constant resolver could plausibly fold. Says nothing about
+ * whether that reference actually resolves; the cascade decides that and
+ * records `unresolved-constant` when it does not.
+ *
+ * Used where the overload set already fixes which slot holds the destination.
+ */
+export declare function isAddressShaped(text: string): boolean;
+/**
+ * STRICT gate — true only when the spelling is confident evidence of an
+ * address, not merely compatible with one.
+ *
+ * The difference from {@link isAddressShaped} is the lowercase bare identifier.
+ * `convertAndSend(topic, payload)` and `convertAndSend(message, processor)` are
+ * the same syntax; only a human reading the names can tell which slot is the
+ * destination, and a name is not something this module is willing to rank as
+ * evidence. So a bare `topic` fails here and the publish is refused, while
+ * `"orders"`, `Topics.ORDERS` and `ORDERS_TOPIC` pass.
+ *
+ * Used ONLY at the arities where a trailing `MessagePostProcessor` overload
+ * collides with the destination-carrying one. Everywhere else the permissive
+ * gate applies, so this stricter rule costs nothing outside the ambiguity.
+ */
+export declare function isConfidentAddressShape(text: string): boolean;
+export interface SpringPlaceholderResult {
+    /** True when the text contained no `${…}` at all. */
+    readonly plain: boolean;
+    /** Key of the FIRST placeholder, in source order. Present whenever `plain`
+     *  is false; the empty string when the placeholder named no key (`${}`). */
+    readonly key?: string;
+    /** Default text of that placeholder, exactly as written, when it had one.
+     *  Absent for a bare `${key}`. The empty string for `${key:}`, which is a
+     *  default that was written and is empty. */
+    readonly defaultValue?: string;
+}
+/**
+ * Read the FIRST Spring property placeholder out of an already-unquoted value.
+ *
+ * NOTHING IS SUBSTITUTED, and that is the rule, not an omission.
+ *
+ * `${key}` cannot resolve: the value lives in a configuration file this index
+ * deliberately does not read into the graph (values may hold credentials — see
+ * `pipeline-phases/spring-config.ts`). The KEY comes back instead, so the
+ * caller can link the node to the `Property` nodes for that key without ever
+ * learning its value.
+ *
+ * `${key:default}` cannot resolve EITHER, which is a correction to this
+ * module's original rule. The default is written in the source, so reading it
+ * is legitimate and it is returned — but it is provenance, never an identity.
+ * A default holds only while the key is not overridden, and whether it is
+ * overridden is a fact about configuration VALUES, which are absent from this
+ * graph by design. Substituting it made `${a.topic:events}` and
+ * `${b.topic:events}` one node and reported a producer/consumer pair between
+ * two services that shared nothing but a copy-pasted fallback. The same
+ * reasoning applies to any placeholder-derived value: a value the configuration
+ * can override is not an identity.
+ *
+ * Only the first placeholder is read because there is nothing to do with the
+ * rest — the value is already unresolvable, and the first key is the one a
+ * reader would look up. A nested default (`${a:${b}}`) needs no special case
+ * under this rule: `a` is the key and `${b}` is the default text, both reported
+ * as written.
+ */
+export declare function resolveSpringPlaceholders(value: string): SpringPlaceholderResult;
+/**
+ * Resolve one candidate to an address, or to a named refusal.
+ *
+ * Four steps, in this order, each of which may decline:
+ *
+ *  1. literal        — `"orders.v1"`, including one element of an array form.
+ *  2. constant       — `Topics.ORDERS`, through the supplied constant resolver.
+ *  3. configuration  — neither `${app.topic}` nor `${app.topic:orders}`
+ *                      resolves; the key, and the default text when there is
+ *                      one, are reported instead.
+ *  4. specification  — the deferred seam; see {@link SpringDestinationResolvers}.
+ *
+ * Steps 1 and 2 both feed step 3: a literal may be a placeholder, and so may
+ * the value a constant folds to (`static final String TOPIC = "${app.topic}"`
+ * is an ordinary way to write one). Skipping step 3 after step 2 would file
+ * that constant's placeholder text as a resolved address — the exact false
+ * identity this module exists to prevent, arrived at one step later.
+ *
+ * Two classes of text are rejected BEFORE step 3, because they are not
+ * addresses in any configuration: a SpEL expression, which the container
+ * evaluates against live beans, and an unescaped string-template interpolation
+ * in a language that interpolates. Order matters between them and the
+ * placeholder rule — `"#{'${app.topics}'.split(',')}"` contains a `${` and
+ * would otherwise be filed under a configuration key that is not really what
+ * it is.
+ *
+ * WHITESPACE. An address is kept exactly as the source wrote it, `" orders "`
+ * included, so `" orders "` is its own node and does not join `"orders"`. That
+ * is a missing connection rather than a false one, which is the trade this
+ * module makes everywhere. The emptiness test below trims, because a
+ * whitespace-only address addresses nothing — the two rules disagree on
+ * purpose, and this is the statement of it.
+ */
+export declare function resolveSpringDestination(candidate: SpringDestinationCandidate, resolvers?: SpringDestinationResolvers): SpringDestinationResolution;