whisper-id 0.4.0 → 0.5.0

package/README.md

@@ -109,9 +109,21 @@ await graph.query("MATCH (n) RETURN n LIMIT $lim", { lim: 5 });  // raw Cypher e
 | `graph.query(cypher, params)` | Raw Cypher escape hatch. → the full `{ columns, rows, statistics }` |
 
 Fifteen multi-step **workflow** methods (`attackPath`, `attackSurface`, `blastRadius`, `typosquat`,
-`indicator`, `routeHealth`, and 9 more) run via the Whisper workflow runner, not a single Cypher
-call, so they are not wired into this SDK yet: calling one rejects with a clear `WhisperError`
-(carrying `.runVia`) telling you which workflow to run. Use `graph.query` for raw Cypher meanwhile.
+`indicator`, `routeHealth`, and 9 more) execute on the Whisper workflow runner and stream
+Server-Sent Events; one call collects the whole run into `{ slug, steps, complete, events }`:
+
+```js
+const run = await graph.typosquat("paypal.com");   // bare value → the flow's primary input
+console.log(run.steps.length, "steps");            // each step: its bound Cypher, columns, rows
+console.log(run.complete.totalLatencyMs, "ms");    // the terminal aggregate context
+
+await graph.attackSurface({ domain: "github.com", level: "deep" });  // named inputs + knobs
+```
+
+Every `graph` method is generated from the Whisper query catalog (never hand-copied, so it
+cannot drift) and links its canonical docs: `graph.identify.docs` →
+`https://www.whisper.security/docs/whisper-graph/procedures/identify`, and the same URL is on
+each method's `@see` tag in your editor.
 
 ### Egress + CLI-backed
 

package/index.d.ts

@@ -151,13 +151,15 @@ export function identity(opts?: IdentityOptions): Promise<AgentItem | null>;
 export function agent(sel: string, opts?: ControlOptions): Promise<AgentItem | null>;
 export function agent(opts?: AgentSelectOptions): Promise<AgentItem | null>;
 
-// ── Graph (keyed Cypher over the Whisper Security graph) ─────────────────────────────
+// ── Graph (keyed: Cypher + flows over the Whisper Security graph) ────────────────────
 // The intelligence half of the keyed surface. Postel two-tier: the keyless identity calls
 // above (verify/verifyDetails/rdap) run with no key and no Cypher; this whole `graph`
-// namespace is KEYED (Kaveh's rule: if it is Cypher, it needs a key). It POSTs raw Cypher to
-// the same endpoint the control plane uses, with the key only in `X-API-Key`. `direct`
-// methods run their Cypher and resolve to a `GraphResult`; the 15 `flow` methods are
-// workflow-runner reads not wired here, so calling one rejects with a clear `WhisperError`.
+// namespace is KEYED (Kaveh's rule: if it is Cypher, it needs a key). The 14 `direct`
+// methods POST their catalog Cypher to /api/query; the 15 `flow` methods execute on the
+// workflow runner (POST gallery/run, Server-Sent Events) and resolve to the collected
+// stream. The key rides only in `X-API-Key`. The method surface below is GENERATED from
+// the Whisper query catalog by scripts/gen-graph.mjs; every method's docs live at the
+// `@see` URL and are also on the function itself as `.docs`.
 
 /** Per-call options for the keyed graph namespace (same shape as the control plane). */
 export interface GraphOptions extends ControlOptions {}
@@ -172,78 +174,435 @@ export interface GraphResult {
 /** A `graph.submit` payload: an indicator observation or a piece of feedback. */
 export interface GraphSubmission {
   kind: "indicator" | "feedback" | string;
+  identifier_kind?: string;
+  identifierKind?: string;
+  value?: string;
+  observation_id?: string;
+  observationId?: string;
+  confidence?: number;
+  first_seen?: string;
+  firstSeen?: string;
+  provenance?: string;
+  query?: string;
+  results?: unknown;
+  comment?: string;
+  severity?: string;
+  v?: number;
   [k: string]: unknown;
 }
 
 /**
- * The keyed graph namespace: typed Cypher methods over the Whisper Security graph, plus a
- * raw `query` escape hatch. Every method needs a key (`{ apiKey }` or `WHISPER_API_KEY`).
+ * Input for a flow method: a bare value for the flow's primary input, a plain object of
+ * named inputs (a known knob name routes to params), or an explicit `{ inputs, params }`.
+ */
+export type GraphFlowInput =
+  | string
+  | number
+  | Record<string, unknown>
+  | { inputs?: Record<string, unknown>; params?: Record<string, unknown> };
+
+/** One Server-Sent Event from a flow run; `data` is JSON-decoded when possible. */
+export interface GraphFlowEvent {
+  event: string;
+  data: unknown;
+}
+
+/**
+ * Result of a flow run: every `step` event's payload (each carries the step's bound
+ * Cypher, columns, and rows), the terminal `complete` payload (the aggregate context;
+ * `null` if the stream ended early), and the full raw event list.
+ */
+export interface GraphFlowResult {
+  slug: string;
+  steps: Record<string, unknown>[];
+  complete: Record<string, unknown> | null;
+  events: GraphFlowEvent[];
+}
+
+/**
+ * The keyed graph namespace: one typed method per catalog entry (14 direct Cypher reads +
+ * 15 workflow-runner flows), plus a raw `query` escape hatch. Every method needs a key
+ * (`{ apiKey }` or `WHISPER_API_KEY`) and carries its canonical docs URL as `.docs`.
  */
 export interface GraphNamespace {
-  /** Raw Cypher escape hatch. Returns the full `{columns,rows,statistics}`. */
+  /**
+   * Raw Cypher escape hatch: run arbitrary Cypher with `params` bound server-side as
+   * $-parameters. Returns the full `{columns,rows,statistics}`.
+   * @see https://www.whisper.security/docs/cypher-api
+   */
   query(cypher: string, params?: Record<string, unknown>, opts?: GraphOptions): Promise<GraphResult>;
 
-  /** Name the vendor and operator role behind a host or IP in one call. */
+  // BEGIN GENERATED: graph catalog (scripts/gen-graph.mjs) - do not edit by hand
+  /**
+   * Assess how resilient a country's core DNS is if it were cut off from the world.
+   *
+   * Could a country still resolve names if it were isolated? Counts how many of the 13 root
+   * letters have in-country DNS_ROOT_INSTANCE anycast nodes, the Global-vs-Local split, the BGP
+   * origin ASNs hosting them, and a resilience grade.
+   *
+   * KEYED flow: streams Server-Sent Events from the workflow runner (slug "anycast-dns-root-sovereignty")
+   * and resolves to the collected { slug, steps, complete, events }.
+   * Inputs: country. Params: instanceType.
+   * @see https://www.whisper.security/docs/recipes/compliance
+   */
+  anycastDnsRootSovereignty(input?: GraphFlowInput, opts?: GraphOptions): Promise<GraphFlowResult>;
+
+  /**
+   * Find the choke points an attacker would target - and how any two things connect.
+   *
+   * From a starting foothold, finds shared dependencies whose compromise reaches furthest; for
+   * any two indicators, traces how they are actually connected.
+   *
+   * KEYED flow: streams Server-Sent Events from the workflow runner (slug "attack-path")
+   * and resolves to the collected { slug, steps, complete, events }.
+   * Inputs: value, other. Params: level.
+   * @see https://www.whisper.security/docs/recipes/attack-path
+   */
+  attackPath(input?: GraphFlowInput, opts?: GraphOptions): Promise<GraphFlowResult>;
+
+  /**
+   * Map everything about a domain that's exposed to the outside world, scored for risk.
+   *
+   * Maps the full external footprint - subdomains, name/mail servers, registrant, third-party
+   * services, connected web - and scores the exposure.
+   *
+   * KEYED flow: streams Server-Sent Events from the workflow runner (slug "attack-surface")
+   * and resolves to the collected { slug, steps, complete, events }.
+   * Inputs: domain. Params: level.
+   * @see https://www.whisper.security/docs/recipes/pentest-recon
+   */
+  attackSurface(input?: GraphFlowInput, opts?: GraphOptions): Promise<GraphFlowResult>;
+
+  /**
+   * Grade a network's routing security and trace conflicts to the domains they'd expose.
+   *
+   * Grades a network on the conflicts/gaps that make route hijacking possible, then traces any
+   * conflict to the specific domains and organisations exposed on the affected blocks.
+   *
+   * KEYED flow: streams Server-Sent Events from the workflow runner (slug "bgp-hijack-exposure")
+   * and resolves to the collected { slug, steps, complete, events }.
+   * Inputs: value.
+   * @see https://www.whisper.security/docs/recipes/bgp-routing
+   */
+  bgpHijackExposure(input?: GraphFlowInput, opts?: GraphOptions): Promise<GraphFlowResult>;
+
+  /**
+   * Pick one asset and see what would break if it failed - and what it depends on in turn.
+   *
+   * Maps dependencies in both directions: everything that breaks if the asset fails (SPOFs) and
+   * everything it relies on (its own DNS/mail/hosting/network supply chain).
+   *
+   * KEYED flow: streams Server-Sent Events from the workflow runner (slug "blast-radius")
+   * and resolves to the collected { slug, steps, complete, events }.
+   * Inputs: indicator. Params: depth.
+   * @see https://www.whisper.security/docs/recipes/soc
+   */
+  blastRadius(input?: GraphFlowInput, opts?: GraphOptions): Promise<GraphFlowResult>;
+
+  /**
+   * Assemble a ready-to-submit dossier for taking down a scam or phishing domain.
+   *
+   * One-pass takedown package: reputation verdict, owner (WHOIS), abuse-list listings, and
+   * surrounding infrastructure, laid out ready to hand to a registrar/host.
+   *
+   * KEYED flow: streams Server-Sent Events from the workflow runner (slug "build-takedown-evidence-package")
+   * and resolves to the collected { slug, steps, complete, events }.
+   * Inputs: domain.
+   * @see https://www.whisper.security/docs/recipes/threat-intel
+   */
+  buildTakedownEvidencePackage(input?: GraphFlowInput, opts?: GraphOptions): Promise<GraphFlowResult>;
+
+  /**
+   * Map an organisation's externally visible AI and agent endpoints from the outside.
+   *
+   * Maps externally visible AI/agent hosts (API, model, agent) from the outside via heuristic
+   * hostname patterns (api./mcp./ai./vector./llm./agent./chat./copilot.). Best-effort leads.
+   *
+   * KEYED flow: streams Server-Sent Events from the workflow runner (slug "discover-ai-agent-infrastructure")
+   * and resolves to the collected { slug, steps, complete, events }.
+   * Inputs: value.
+   * @see https://www.whisper.security/docs/recipes/pentest-recon
+   */
+  discoverAiAgentInfrastructure(input?: GraphFlowInput, opts?: GraphOptions): Promise<GraphFlowResult>;
+
+  /**
+   * Investigate one suspicious domain, IP, or network in depth and get a clear picture of the threat and everything connected to it.
+   *
+   * Deep-dive: works outward across the whole footprint (related domains, real origins behind
+   * CDN, neighbouring infra), threat-checks each node, never inherits maliciousness from shared
+   * infra; labelled posture, no score.
+   *
+   * KEYED flow: streams Server-Sent Events from the workflow runner (slug "indicator")
+   * and resolves to the collected { slug, steps, complete, events }.
+   * Inputs: indicator.
+   * @see https://www.whisper.security/docs/recipes/soc
+   */
+  indicator(input?: GraphFlowInput, opts?: GraphOptions): Promise<GraphFlowResult>;
+
+  /**
+   * Turn one domain or IP into a full context card - owner, hosting, mail, location, reputation at a glance.
+   *
+   * Fills the picture for one indicator: registrant (WHOIS), hosting + country, mail/name
+   * servers, network behind it, reputation read.
+   *
+   * KEYED flow: streams Server-Sent Events from the workflow runner (slug "indicator-enrichment")
+   * and resolves to the collected { slug, steps, complete, events }.
+   * Inputs: value.
+   * @see https://www.whisper.security/docs/recipes/dns-email
+   */
+  indicatorEnrichment(input?: GraphFlowInput, opts?: GraphOptions): Promise<GraphFlowResult>;
+
+  /**
+   * Trace one indicator to its true owner and full estate, even behind privacy screens and CDNs.
+   *
+   * Works out the true operator (even behind privacy WHOIS), de-cloaks CDN-fronted sites to real
+   * servers, pivots to the rest of that owner's estate across every layer.
+   *
+   * KEYED flow: streams Server-Sent Events from the workflow runner (slug "infrastructure-mapping")
+   * and resolves to the collected { slug, steps, complete, events }.
+   * Inputs: value. Params: level.
+   * @see https://www.whisper.security/docs/recipes/compliance
+   */
+  infrastructureMapping(input?: GraphFlowInput, opts?: GraphOptions): Promise<GraphFlowResult>;
+
+  /**
+   * Grade an organisation for over-reliance on single providers, regions, or facilities.
+   *
+   * Grades how concentrated infra is - too much riding on one provider/region/data-centre/cable
+   * landing - surfacing SPOFs for resilience and DORA/NIS2 fourth-party risk.
+   *
+   * KEYED flow: streams Server-Sent Events from the workflow runner (slug "map-supply-chain-concentration")
+   * and resolves to the collected { slug, steps, complete, events }.
+   * Inputs: domain.
+   * @see https://www.whisper.security/docs/recipes/compliance
+   */
+  mapSupplyChainConcentration(input?: GraphFlowInput, opts?: GraphOptions): Promise<GraphFlowResult>;
+
+  /**
+   * Check a domain's name servers for the misconfigurations that enable DNS hijacking.
+   *
+   * Audits delegation, flags stale/mismatched/lame nameservers, sizes each provider's share,
+   * surfaces registry facts - catches delegation weakness before exploit.
+   *
+   * KEYED flow: streams Server-Sent Events from the workflow runner (slug "nameserver-hijack-dns-consistency")
+   * and resolves to the collected { slug, steps, complete, events }.
+   * Inputs: value.
+   * @see https://www.whisper.security/docs/recipes/dns-email
+   */
+  nameserverHijackDnsConsistency(input?: GraphFlowInput, opts?: GraphOptions): Promise<GraphFlowResult>;
+
+  /**
+   * Profile a network or address block into a full routing and reachability health card.
+   *
+   * Health card for a network/block: what it announces, peers/transit, single-upstream lean,
+   * RPKI protection - the one-look reach & resilience report.
+   *
+   * KEYED flow: streams Server-Sent Events from the workflow runner (slug "route-health")
+   * and resolves to the collected { slug, steps, complete, events }.
+   * Inputs: target.
+   * @see https://www.whisper.security/docs/recipes/bgp-routing
+   */
+  routeHealth(input?: GraphFlowInput, opts?: GraphOptions): Promise<GraphFlowResult>;
+
+  /**
+   * Find subdomains that point at abandoned services an attacker could claim.
+   *
+   * Walks subdomains and flags ones aiming at deprovisioned targets (dangling CNAME whose target
+   * no longer resolves) so you can reclaim/remove before someone else does. CNAME layer is
+   * prod-ahead.
+   *
+   * KEYED flow: streams Server-Sent Events from the workflow runner (slug "subdomain-takeover")
+   * and resolves to the collected { slug, steps, complete, events }.
+   * Inputs: value.
+   * @see https://www.whisper.security/docs/recipes/pentest-recon
+   */
+  subdomainTakeover(input?: GraphFlowInput, opts?: GraphOptions): Promise<GraphFlowResult>;
+
+  /**
+   * Find registered look-alikes of your brand and check which ones are dangerous.
+   *
+   * Finds registered impersonations across misspellings/risky TLDs, separates your own defensive
+   * domains from strangers', flags fresh/privacy/abuse-listed ones into a prioritised list.
+   *
+   * KEYED flow: streams Server-Sent Events from the workflow runner (slug "typosquat")
+   * and resolves to the collected { slug, steps, complete, events }.
+   * Inputs: domain.
+   * @see https://www.whisper.security/docs/recipes/brand-protection
+   */
+  typosquat(input?: GraphFlowInput, opts?: GraphOptions): Promise<GraphFlowResult>;
+
+  /**
+   * Name the vendor and operator role behind a host or IP in one call.
+   *
+   * Resolves a host/IP to its canonical vendor, category and operator roles (DNS_OPERATOR / CDN
+   * / ORIGIN_AS / MAIL_RECEIVER) with a confidence band.
+   *
+   * KEYED. Cypher: CALL whisper.identify([$v]) YIELD host, vendor_id, canonical_name, category, roles, host_class, band
+   * Returns columns: host, vendor_id, canonical_name, category, roles, host_class, band.
+   * @see https://www.whisper.security/docs/whisper-graph/procedures/identify
+   */
   identify(value: string, opts?: GraphOptions): Promise<GraphResult>;
-  /** Labelled threat posture for a host or IP: malicious, benign, or unknown. */
+
+  /**
+   * Get a labelled threat posture for a host or IP - malicious, benign, or unknown.
+   *
+   * Returns a posture label + severity band + sub-labels + coverage + evidence for an indicator;
+   * benign-allowlisted vs malicious-evidenced, never a bare score.
+   *
+   * KEYED. Cypher: CALL whisper.assess([$v]) YIELD host, label, band, sub_labels, coverage, evidence
+   * Returns columns: host, label, band, sub_labels, coverage, evidence.
+   * @see https://www.whisper.security/docs/whisper-graph/procedures
+   */
   assess(value: string, opts?: GraphOptions): Promise<GraphResult>;
-  /** Generate look-alike domain variants of a brand and see which are registered. */
+
+  /**
+   * Generate look-alike domain variants of a brand and see which are registered.
+   *
+   * Enumerates permutations (omission, bitsquatting, ...) of a domain, flags which exist, with a
+   * per-variant confidence.
+   *
+   * KEYED. Cypher: CALL whisper.variants($v) YIELD variant, method, exists, confidence
+   * Returns columns: variant, method, exists, confidence.
+   * @see https://www.whisper.security/docs/whisper-graph/procedures/variants
+   */
   variants(value: string, opts?: GraphOptions): Promise<GraphResult>;
-  /** Walk the graph to the nearest known vendors behind a host, with channel and confidence. */
+
+  /**
+   * Walk the graph to the nearest known vendors behind a host, with the channel and confidence.
+   *
+   * Structural attribution: returns nearest_known_vendors with the channel (DELEGATED_TO /
+   * ORIGIN_AS) and confidence, plus siblings and coverage - explains WHY a host maps to a
+   * vendor.
+   *
+   * KEYED. Cypher: CALL whisper.walk($v) YIELD coverage, host, nearest_known_vendors, no_atlas_match, siblings
+   * Returns columns: coverage, host, nearest_known_vendors, no_atlas_match, siblings.
+   * @see https://www.whisper.security/docs/whisper-graph/procedures
+   */
   walk(value: string, opts?: GraphOptions): Promise<GraphResult>;
-  /** Score an indicator against the threat feeds and explain exactly why. */
+
+  /**
+   * Score an indicator against the threat feeds and explain exactly why.
+   *
+   * Threat-intel scorer: score + level + human explanation + the feeds it is listed in (feedId,
+   * weight, firstSeen/lastSeen). Two live forms: bare CALL explain($v) (full columns) and CALL
+   * whisper.explain($v) (restricted YIELD).
+   *
+   * KEYED. Cypher: CALL whisper.explain($v) YIELD indicator, score, level, explanation, sources
+   * Returns columns: indicator, score, level, explanation, sources.
+   * @see https://www.whisper.security/docs/whisper-graph/procedures/explain
+   */
   explain(value: string, opts?: GraphOptions): Promise<GraphResult>;
-  /** Reduce any hostname to its registrable apex (eTLD+1) via the Public Suffix List. */
+
+  /**
+   * Reduce any hostname to its registrable apex (eTLD+1) via the Public Suffix List.
+   *
+   * PSL-correct eTLD+1: www.foo.co.uk -> foo.co.uk. The right way to group hosts by the thing
+   * someone actually registered.
+   *
+   * KEYED. Cypher: CALL whisper.psl.tldPlusOne($v) YIELD apex
+   * Returns columns: apex.
+   * @see https://www.whisper.security/docs/whisper-graph/procedures/helpers
+   */
   pslTldplusone(value: string, opts?: GraphOptions): Promise<GraphResult>;
-  /** Check whether a domain is a PSL private-section suffix and who submitted it. */
+
+  /**
+   * Check whether a domain is a PSL private-section suffix and who submitted it.
+   *
+   * For a PSL private-section suffix, returns the submitting org/login and evidence kind +
+   * confidence; found=false for ordinary registrable domains.
+   *
+   * KEYED. Cypher: CALL whisper.psl.affiliation($v) YIELD found, suffix, submitterOrg, submitterLogin, evidenceKind, confidence
+   * Returns columns: found, suffix, submitterOrg, submitterLogin, evidenceKind, confidence.
+   * @see https://www.whisper.security/docs/whisper-graph/procedures/helpers
+   */
   pslAffiliation(value: string, opts?: GraphOptions): Promise<GraphResult>;
-  /** Find the real origin IPs behind a CDN-fronted domain, ranked by confidence. */
+
+  /**
+   * Find the real origin IPs behind a CDN-fronted domain, ranked by confidence.
+   *
+   * Candidate origin IPs behind a CDN with confidence, the methods that found them (e.g.
+   * links_to), and the hosting ASN/name - de-cloaks to the real server.
+   *
+   * KEYED. Cypher: CALL whisper.origins($v) YIELD ip, confidence, methods, asn, asnName, kind
+   * Returns columns: ip, confidence, methods, asn, asnName, kind.
+   * @see https://www.whisper.security/docs/whisper-graph/procedures/origins
+   */
   origins(value: string, opts?: GraphOptions): Promise<GraphResult>;
-  /** Full historical WHOIS timeline for a domain. */
+
+  /**
+   * Get the full historical WHOIS timeline for a domain.
+   *
+   * Every observed WHOIS snapshot over time: create/update/expiry, registrar, registrant,
+   * country, nameservers - the ownership/registration story.
+   *
+   * KEYED. Cypher: CALL whisper.history($v)
+   * Returns columns: indicator, type, queryTime, createDate, updateDate, expiryDate, registrar, registrant, country, nameServers, cached.
+   * @see https://www.whisper.security/docs/whisper-graph/procedures/history
+   */
   history(value: string, opts?: GraphOptions): Promise<GraphResult>;
-  /** WHOIS-only historical timeline for a domain. */
+
+  /**
+   * Get the WHOIS-only historical timeline for a domain.
+   *
+   * The registration-record projection of the history timeline: create/update/expiry, registrar,
+   * registrant, country, nameservers per snapshot.
+   *
+   * KEYED. Cypher: CALL whisper.history.whois($v) YIELD queryTime, createDate, updateDate, expiryDate, registrar, registrant, country, nameServers
+   * Returns columns: queryTime, createDate, updateDate, expiryDate, registrar, registrant, country, nameServers.
+   * @see https://www.whisper.security/docs/whisper-graph/procedures/history
+   */
   historyWhois(value: string, opts?: GraphOptions): Promise<GraphResult>;
-  /** List the member ASNs of an AS-SET macro. */
+
+  /**
+   * List the member ASNs of an AS-SET macro.
+   *
+   * Expands an AS-SET name (e.g. AS-CLOUDFLARE) to its member ASNs and source RIR. Arg is a
+   * STRING as-set name, not an integer ASN. (Membership is sparsely populated in the current
+   * graph.)
+   *
+   * KEYED. Cypher: CALL whisper.asSet($v) YIELD asSetName, memberAsn, sourceRir
+   * Returns columns: asSetName, memberAsn, sourceRir.
+   * @see https://www.whisper.security/docs/whisper-graph/procedures
+   */
   asset(value: string, opts?: GraphOptions): Promise<GraphResult>;
-  /** Check whether an IP is a known Tor exit relay. */
+
+  /**
+   * Check whether an IP is a known Tor exit relay.
+   *
+   * Live Tor exit-node check: found + fingerprint + exit-address count + source + ingest time
+   * for an IPv4.
+   *
+   * KEYED. Cypher: CALL whisper.lookupTorRelay($v) YIELD indicator, found, fingerprint, exitAddressCount, source, ingestedAt
+   * Returns columns: indicator, found, fingerprint, exitAddressCount, source, ingestedAt.
+   * @see https://www.whisper.security/docs/whisper-graph/procedures/helpers
+   */
   lookupTorRelay(value: string, opts?: GraphOptions): Promise<GraphResult>;
-  /** List every node and relationship type in the graph with counts and examples. No input. */
+
+  /**
+   * List every node and relationship type in the graph with counts and examples.
+   *
+   * The self-describing schema: node/relationship types with counts, descriptions, examples,
+   * source/target labels and query best-practices - the map of what the graph holds.
+   *
+   * KEYED. Cypher: CALL db.schema()
+   * Returns columns: type, name, count, description, example, sourceLabels, targetLabels, fastPatterns, slowPatterns, bestPractices.
+   * @see https://www.whisper.security/docs/whisper-graph/schema
+   */
   dbSchema(opts?: GraphOptions): Promise<GraphResult>;
-  /** Contribute an indicator observation or feedback back into the graph (keyed WRITE). */
-  submit(payload: GraphSubmission, opts?: GraphOptions): Promise<GraphResult>;
 
-  // The 15 `flow` workflow-runner methods. Not wired into this SDK: each rejects with a clear
-  // WhisperError (carrying `.runVia`). Run them via the console/agent workflow runner.
-  /** Workflow (run_workflow): assess a country's DNS-root sovereignty. Not wired here. */
-  anycastDnsRootSovereignty(opts?: GraphOptions): Promise<never>;
-  /** Workflow (run_workflow): find the choke points an attacker would target. Not wired here. */
-  attackPath(opts?: GraphOptions): Promise<never>;
-  /** Workflow (run_workflow): map a domain's externally exposed attack surface. Not wired here. */
-  attackSurface(opts?: GraphOptions): Promise<never>;
-  /** Workflow (run_workflow): grade a network's routing security. Not wired here. */
-  bgpHijackExposure(opts?: GraphOptions): Promise<never>;
-  /** Workflow (run_workflow): what breaks if one asset fails, and its dependencies. Not wired here. */
-  blastRadius(opts?: GraphOptions): Promise<never>;
-  /** Workflow (run_workflow): assemble a takedown evidence dossier. Not wired here. */
-  buildTakedownEvidencePackage(opts?: GraphOptions): Promise<never>;
-  /** Workflow (run_workflow): map an org's externally visible AI/agent endpoints. Not wired here. */
-  discoverAiAgentInfrastructure(opts?: GraphOptions): Promise<never>;
-  /** Workflow (run_workflow): investigate one indicator in depth. Not wired here. */
-  indicator(opts?: GraphOptions): Promise<never>;
-  /** Workflow (run_workflow): turn one domain/IP into a full context card. Not wired here. */
-  indicatorEnrichment(opts?: GraphOptions): Promise<never>;
-  /** Workflow (run_workflow): trace an indicator to its true owner and estate. Not wired here. */
-  infrastructureMapping(opts?: GraphOptions): Promise<never>;
-  /** Workflow (run_workflow): grade an org for supply-chain concentration. Not wired here. */
-  mapSupplyChainConcentration(opts?: GraphOptions): Promise<never>;
-  /** Workflow (run_workflow): check name servers for DNS-hijack misconfigurations. Not wired here. */
-  nameserverHijackDnsConsistency(opts?: GraphOptions): Promise<never>;
-  /** Workflow (run_workflow): profile a network/block into a routing health card. Not wired here. */
-  routeHealth(opts?: GraphOptions): Promise<never>;
-  /** Workflow (run_workflow): find subdomains that point at claimable services. Not wired here. */
-  subdomainTakeover(opts?: GraphOptions): Promise<never>;
-  /** Workflow (run_workflow): find registered look-alikes of your brand. Not wired here. */
-  typosquat(opts?: GraphOptions): Promise<never>;
+  /**
+   * Contribute an indicator observation or feedback back into the graph (requires an API key).
+   *
+   * The write channel: submit an indicator/feedback with an attributable API key (anonymous
+   * submits are refused to preserve K-anonymity). Keyed-only by design.
+   *
+   * KEYED write: CALL whisper.submit({...}) with the payload fields bound as $-parameters.
+   * Fields: kind, identifier_kind, value, observation_id, confidence, first_seen, provenance, query, results, comment, severity, v (kind required).
+   * Returns columns: observation_id, kind, accepted, idempotent, promotion_state, k_bucket, advisory, v.
+   * @see https://www.whisper.security/docs/cypher-api
+   */
+  submit(payload: GraphSubmission, opts?: GraphOptions): Promise<GraphResult>;
+  // END GENERATED: graph catalog
 }
 
 /** The keyed graph namespace. `import { graph } from "whisper-id"`. */

package/index.js

@@ -466,11 +466,12 @@ export async function agent(sel = {}, maybeOpts) {
 // where rows are already column-keyed objects), so it has its own choke point, callGraph().
 //
 // Source of truth for the 29 methods is the Whisper query catalog (catalog.json +
-// sdk-methods.json); the tables below are copied from it (keyed by exec.mode). A test
-// asserts the count so the two cannot silently drift. 14 `direct` entries run their catalog
-// Cypher against /api/query; 15 `flow` entries run via the workflow runner (run_workflow),
-// which is NOT a single /api/query Cypher, so they are shipped as clearly-noted stubs and
-// are not wired to an engine here. graph.query() is the raw escape hatch.
+// sdk-methods.json): the GRAPH_METHODS table below is GENERATED from it by
+// scripts/gen-graph.mjs (`npm run gen`), so this SDK cannot drift from the catalog. The
+// 14 `direct` entries run their catalog Cypher against /api/query; the 15 `flow` entries
+// EXECUTE on the workflow runner (POST gallery/run, Server-Sent Events) via callFlow().
+// Every method carries its canonical docs URL as `.docs`. graph.query() is the raw
+// escape hatch.
 
 function graphUrl() {
   // Defaults to the control endpoint, which already IS the graph endpoint. Override for tests
@@ -550,44 +551,45 @@ async function callGraph(cypher, params, opts = {}, methodName = "query") {
   return normalizeGraph(body);
 }
 
-// The 14 `direct` catalog entries: id (camelCased) -> its catalog Cypher. Every one binds a
-// single input as $v (paramName `v` in the catalog), except dbSchema (no input) and submit
-// (a write map, handled below). Copied verbatim from whisper-catalog/catalog.json.
-const GRAPH_DIRECT = {
-  identify: "CALL whisper.identify([$v]) YIELD host, vendor_id, canonical_name, category, roles, host_class, band",
-  assess: "CALL whisper.assess([$v]) YIELD host, label, band, sub_labels, coverage, evidence",
-  variants: "CALL whisper.variants($v) YIELD variant, method, exists, confidence",
-  walk: "CALL whisper.walk($v) YIELD coverage, host, nearest_known_vendors, no_atlas_match, siblings",
-  explain: "CALL whisper.explain($v) YIELD indicator, score, level, explanation, sources",
-  pslTldplusone: "CALL whisper.psl.tldPlusOne($v) YIELD apex",
-  pslAffiliation: "CALL whisper.psl.affiliation($v) YIELD found, suffix, submitterOrg, submitterLogin, evidenceKind, confidence",
-  origins: "CALL whisper.origins($v) YIELD ip, confidence, methods, asn, asnName, kind",
-  history: "CALL whisper.history($v)",
-  historyWhois: "CALL whisper.history.whois($v) YIELD queryTime, createDate, updateDate, expiryDate, registrar, registrant, country, nameServers",
-  asset: "CALL whisper.asSet($v) YIELD asSetName, memberAsn, sourceRir",
-  lookupTorRelay: "CALL whisper.lookupTorRelay($v) YIELD indicator, found, fingerprint, exitAddressCount, source, ingestedAt",
-};
-
-// The 15 `flow` catalog entries: id (camelCased) -> its runVia slug. These are multi-step
-// read workflows run by the console/agent workflow runner, NOT a single /api/query Cypher,
-// so they are not wired to an engine in this SDK. Copied verbatim from the catalog.
-const GRAPH_FLOW = {
-  anycastDnsRootSovereignty: "run_workflow (anycast-dns-root-sovereignty)",
-  attackPath: "run_workflow (attack-path)",
-  attackSurface: "run_workflow (attack-surface)",
-  bgpHijackExposure: "run_workflow (bgp-hijack-exposure)",
-  blastRadius: "run_workflow (blast-radius)",
-  buildTakedownEvidencePackage: "run_workflow (build-takedown-evidence-package)",
-  discoverAiAgentInfrastructure: "run_workflow (discover-ai-agent-infrastructure)",
-  indicator: "run_workflow (indicator)",
-  indicatorEnrichment: "run_workflow (indicator-enrichment)",
-  infrastructureMapping: "run_workflow (infrastructure-mapping)",
-  mapSupplyChainConcentration: "run_workflow (map-supply-chain-concentration)",
-  nameserverHijackDnsConsistency: "run_workflow (nameserver-hijack-dns-consistency)",
-  routeHealth: "run_workflow (route-health)",
-  subdomainTakeover: "run_workflow (subdomain-takeover)",
-  typosquat: "run_workflow (typosquat)",
-};
+// BEGIN GENERATED: graph catalog (scripts/gen-graph.mjs) - do not edit by hand
+// The Whisper query catalog, one row per entry (14 direct + 15 flow), in catalog order.
+// A direct row carries its catalog Cypher (input bound as a $-parameter); a flow row
+// carries its gallery/run slug plus the input/param names the workflow runner accepts;
+// the map-call row (submit) enumerates its fields. `docs` is the canonical docs URL.
+const GRAPH_DOCS_BASE = "https://www.whisper.security";
+const GRAPH_FLOW_RUN_URL = "https://console.whisper.security/api/gallery/run";
+const GRAPH_METHODS = [
+  { name: "anycastDnsRootSovereignty", mode: "flow", slug: "anycast-dns-root-sovereignty", primary: "country", inputs: ["country"], params: ["instanceType"], docs: GRAPH_DOCS_BASE + "/docs/recipes/compliance" },
+  { name: "attackPath", mode: "flow", slug: "attack-path", primary: "value", inputs: ["value", "other"], params: ["level"], docs: GRAPH_DOCS_BASE + "/docs/recipes/attack-path" },
+  { name: "attackSurface", mode: "flow", slug: "attack-surface", primary: "domain", inputs: ["domain"], params: ["level"], docs: GRAPH_DOCS_BASE + "/docs/recipes/pentest-recon" },
+  { name: "bgpHijackExposure", mode: "flow", slug: "bgp-hijack-exposure", primary: "value", inputs: ["value"], params: [], docs: GRAPH_DOCS_BASE + "/docs/recipes/bgp-routing" },
+  { name: "blastRadius", mode: "flow", slug: "blast-radius", primary: "indicator", inputs: ["indicator"], params: ["depth"], docs: GRAPH_DOCS_BASE + "/docs/recipes/soc" },
+  { name: "buildTakedownEvidencePackage", mode: "flow", slug: "build-takedown-evidence-package", primary: "domain", inputs: ["domain"], params: [], docs: GRAPH_DOCS_BASE + "/docs/recipes/threat-intel" },
+  { name: "discoverAiAgentInfrastructure", mode: "flow", slug: "discover-ai-agent-infrastructure", primary: "value", inputs: ["value"], params: [], docs: GRAPH_DOCS_BASE + "/docs/recipes/pentest-recon" },
+  { name: "indicator", mode: "flow", slug: "indicator", primary: "indicator", inputs: ["indicator"], params: [], docs: GRAPH_DOCS_BASE + "/docs/recipes/soc" },
+  { name: "indicatorEnrichment", mode: "flow", slug: "indicator-enrichment", primary: "value", inputs: ["value"], params: [], docs: GRAPH_DOCS_BASE + "/docs/recipes/dns-email" },
+  { name: "infrastructureMapping", mode: "flow", slug: "infrastructure-mapping", primary: "value", inputs: ["value"], params: ["level"], docs: GRAPH_DOCS_BASE + "/docs/recipes/compliance" },
+  { name: "mapSupplyChainConcentration", mode: "flow", slug: "map-supply-chain-concentration", primary: "domain", inputs: ["domain"], params: [], docs: GRAPH_DOCS_BASE + "/docs/recipes/compliance" },
+  { name: "nameserverHijackDnsConsistency", mode: "flow", slug: "nameserver-hijack-dns-consistency", primary: "value", inputs: ["value"], params: [], docs: GRAPH_DOCS_BASE + "/docs/recipes/dns-email" },
+  { name: "routeHealth", mode: "flow", slug: "route-health", primary: "target", inputs: ["target"], params: [], docs: GRAPH_DOCS_BASE + "/docs/recipes/bgp-routing" },
+  { name: "subdomainTakeover", mode: "flow", slug: "subdomain-takeover", primary: "value", inputs: ["value"], params: [], docs: GRAPH_DOCS_BASE + "/docs/recipes/pentest-recon" },
+  { name: "typosquat", mode: "flow", slug: "typosquat", primary: "domain", inputs: ["domain"], params: [], docs: GRAPH_DOCS_BASE + "/docs/recipes/brand-protection" },
+  { name: "identify", mode: "direct", input: "v", cypher: "CALL whisper.identify([$v]) YIELD host, vendor_id, canonical_name, category, roles, host_class, band", docs: GRAPH_DOCS_BASE + "/docs/whisper-graph/procedures/identify" },
+  { name: "assess", mode: "direct", input: "v", cypher: "CALL whisper.assess([$v]) YIELD host, label, band, sub_labels, coverage, evidence", docs: GRAPH_DOCS_BASE + "/docs/whisper-graph/procedures" },
+  { name: "variants", mode: "direct", input: "v", cypher: "CALL whisper.variants($v) YIELD variant, method, exists, confidence", docs: GRAPH_DOCS_BASE + "/docs/whisper-graph/procedures/variants" },
+  { name: "walk", mode: "direct", input: "v", cypher: "CALL whisper.walk($v) YIELD coverage, host, nearest_known_vendors, no_atlas_match, siblings", docs: GRAPH_DOCS_BASE + "/docs/whisper-graph/procedures" },
+  { name: "explain", mode: "direct", input: "v", cypher: "CALL whisper.explain($v) YIELD indicator, score, level, explanation, sources", docs: GRAPH_DOCS_BASE + "/docs/whisper-graph/procedures/explain" },
+  { name: "pslTldplusone", mode: "direct", input: "v", cypher: "CALL whisper.psl.tldPlusOne($v) YIELD apex", docs: GRAPH_DOCS_BASE + "/docs/whisper-graph/procedures/helpers" },
+  { name: "pslAffiliation", mode: "direct", input: "v", cypher: "CALL whisper.psl.affiliation($v) YIELD found, suffix, submitterOrg, submitterLogin, evidenceKind, confidence", docs: GRAPH_DOCS_BASE + "/docs/whisper-graph/procedures/helpers" },
+  { name: "origins", mode: "direct", input: "v", cypher: "CALL whisper.origins($v) YIELD ip, confidence, methods, asn, asnName, kind", docs: GRAPH_DOCS_BASE + "/docs/whisper-graph/procedures/origins" },
+  { name: "history", mode: "direct", input: "v", cypher: "CALL whisper.history($v)", docs: GRAPH_DOCS_BASE + "/docs/whisper-graph/procedures/history" },
+  { name: "historyWhois", mode: "direct", input: "v", cypher: "CALL whisper.history.whois($v) YIELD queryTime, createDate, updateDate, expiryDate, registrar, registrant, country, nameServers", docs: GRAPH_DOCS_BASE + "/docs/whisper-graph/procedures/history" },
+  { name: "asset", mode: "direct", input: "v", cypher: "CALL whisper.asSet($v) YIELD asSetName, memberAsn, sourceRir", docs: GRAPH_DOCS_BASE + "/docs/whisper-graph/procedures" },
+  { name: "lookupTorRelay", mode: "direct", input: "v", cypher: "CALL whisper.lookupTorRelay($v) YIELD indicator, found, fingerprint, exitAddressCount, source, ingestedAt", docs: GRAPH_DOCS_BASE + "/docs/whisper-graph/procedures/helpers" },
+  { name: "dbSchema", mode: "direct", input: null, cypher: "CALL db.schema()", docs: GRAPH_DOCS_BASE + "/docs/whisper-graph/schema" },
+  { name: "submit", mode: "direct", proc: "whisper.submit", fields: [["kind", "kind"], ["identifierKind", "identifier_kind"], ["value", "value"], ["observationId", "observation_id"], ["confidence", "confidence"], ["firstSeen", "first_seen"], ["provenance", "provenance"], ["query", "query"], ["results", "results"], ["comment", "comment"], ["severity", "severity"], ["v", "v"]], requires: ["kind"], docs: GRAPH_DOCS_BASE + "/docs/cypher-api" },
+];
+// END GENERATED: graph catalog
 
 // Coerce a liberal first arg into the string value bound as $v. Accepts a bare value or a
 // { value } / { v } wrapper; empty is rejected with a clear error, never an opaque failure.
@@ -607,48 +609,225 @@ function graphValue(name, value) {
  * Run raw Cypher against the Whisper Security graph (keyed). The escape hatch under every
  * typed method: `graph.query("MATCH (n) RETURN n LIMIT 1", {}, { apiKey })`. Returns the
  * full `{ columns, rows, statistics }` (rows are objects keyed by column name).
+ * @see https://www.whisper.security/docs/cypher-api
  */
 async function graphQuery(cypher, params, opts = {}) {
   if (!cypher || !String(cypher).trim()) throw new WhisperError("graph.query() needs a Cypher string");
   return callGraph(String(cypher), params || {}, opts, "query");
 }
 
-// Build the namespace: query + a typed method per catalog entry. Direct methods run their
-// Cypher; flow methods throw a clear, honest "runs via the workflow runner, not wired here"
-// error (never a silent no-op) and carry .runVia for programmatic inspection.
-const graph = { query: graphQuery };
-
-for (const [name, cypher] of Object.entries(GRAPH_DIRECT)) {
-  graph[name] = async (value, opts = {}) => callGraph(cypher, { v: graphValue(name, value) }, opts, name);
+// ── Flow runner (gallery/run, Server-Sent Events) ───────────────────────────────────
+// A flow entry is a multi-step read workflow orchestrated by the Whisper workflow runner:
+// POST {slug, inputs, params} to the gallery/run endpoint (keyed, X-API-Key) and consume
+// the SSE stream. Each `step` event carries a step's bound Cypher + rows; the terminal
+// `complete` event carries the aggregate context. callFlow() collects the whole stream and
+// resolves to { slug, steps, complete, events } - one call, the full flow.
+
+function flowRunUrl() {
+  return process.env.WHISPER_FLOW_URL || GRAPH_FLOW_RUN_URL;
+}
+
+// Liberal-accept (RFC 761): coerce the caller's input into the runner's {inputs, params}.
+// A bare value binds to the flow's primary input; a plain object routes each key by name
+// (a known knob name goes to params, everything else to inputs); an explicit
+// { inputs, params } wrapper passes through untouched.
+function flowBody(m, input) {
+  const inputs = {};
+  const params = {};
+  if (input === null || input === undefined) return { inputs, params };
+  if (typeof input !== "object" || Array.isArray(input)) {
+    const v = String(input).trim();
+    if (v === "") throw new WhisperError(`graph.${m.name}() needs a value for its \`${m.primary}\` input (a host, IP, domain, ASN, or prefix)`);
+    inputs[m.primary] = v;
+    return { inputs, params };
+  }
+  if ((input.inputs && typeof input.inputs === "object") || (input.params && typeof input.params === "object")) {
+    return { inputs: { ...(input.inputs || {}) }, params: { ...(input.params || {}) } };
+  }
+  for (const [k, v] of Object.entries(input)) {
+    if (v === undefined) continue;
+    if (m.params.includes(k)) params[k] = v;
+    else inputs[k] = v;
+  }
+  return { inputs, params };
 }
 
-/** List every node and relationship type in the graph with counts and examples (keyed). No input. */
-graph.dbSchema = async (opts = {}) => callGraph("CALL db.schema()", {}, opts, "dbSchema");
+// Parse one SSE record ("event: x\ndata: {...}") into { event, data }; data is JSON-decoded
+// when possible, else kept as the raw string. Never throws on shape.
+function parseSseRecord(record) {
+  let event = "message";
+  const dataLines = [];
+  for (const line of record.split("\n")) {
+    if (line.startsWith("event:")) event = line.slice(6).trim();
+    else if (line.startsWith("data:")) dataLines.push(line.slice(5).replace(/^ /, ""));
+  }
+  let data = dataLines.join("\n");
+  try {
+    data = JSON.parse(data);
+  } catch {
+    // not JSON - keep the raw string
+  }
+  return { event, data };
+}
 
-/**
- * Contribute an indicator observation or feedback back into the graph (keyed WRITE). Pass
- * `{ kind: "indicator" | "feedback", ...fields }`. The payload is bound as a single Cypher
- * parameter (injection-safe). The server enforces its own write scopes and rejects anonymous
- * callers, so a scope/quota fault surfaces as the server's WhisperError detail.
- */
-graph.submit = async (payload, opts = {}) => {
-  const p = payload && typeof payload === "object" && !Array.isArray(payload) ? payload : {};
-  if (!p.kind || String(p.kind).trim() === "") {
-    throw new WhisperError("graph.submit() needs a { kind } of 'indicator' or 'feedback' (plus its fields)");
-  }
-  return callGraph("CALL whisper.submit($submission)", { submission: p }, opts, "submit");
-};
-
-for (const [name, runVia] of Object.entries(GRAPH_FLOW)) {
-  graph[name] = () => {
-    const err = new WhisperError(
-      `graph.${name}() is a multi-step read workflow: it runs via the Whisper workflow runner ` +
-        `(${runVia}), not a single /api/query Cypher, and is not wired into this SDK yet. Use ` +
-        "graph.query() for a raw Cypher call, or run the workflow via the console/agent runner."
+// The one place that talks to the workflow runner. Requires a key (shared resolveKey),
+// POSTs {slug, inputs, params}, consumes the SSE stream, and resolves to the collected
+// { slug, steps, complete, events }. Flows are multi-step, so the default timeout is 5
+// minutes (override with opts.timeout). On an HTTP error, an `error` event, or a stream
+// that ends with no result at all, throws a WhisperError with the server's clear detail.
+async function callFlow(m, input, opts = {}) {
+  const key = resolveKey(opts);
+  if (!key) {
+    throw new WhisperError(
+      `\`graph.${m.name}\` needs a Whisper API key: pass { apiKey } or set WHISPER_API_KEY. ` +
+        "(verify/verifyDetails/rdap are keyless and need no key; flows run keyed on the workflow runner.)"
     );
-    err.runVia = runVia;
-    return Promise.reject(err);
+  }
+  const { inputs, params } = flowBody(m, input);
+  const url = flowRunUrl();
+  const timeout = opts.timeout || 300000;
+  const ctrl = new AbortController();
+  const t = setTimeout(() => ctrl.abort(), timeout);
+  try {
+    let res;
+    try {
+      res = await fetch(url, {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/json",
+          Accept: "text/event-stream",
+          "X-API-Key": key,
+          "User-Agent": UA,
+        },
+        body: JSON.stringify({ slug: m.slug, inputs, params }),
+        signal: ctrl.signal,
+      });
+    } catch (err) {
+      throw new WhisperError(`could not reach the Whisper workflow runner at ${url}: ${err && err.message ? err.message : err}`);
+    }
+    if (res.status >= 400) {
+      let body = null;
+      try {
+        body = await res.json();
+      } catch {
+        body = null;
+      }
+      const e = body && typeof body === "object" ? body : {};
+      const werr = new WhisperError(
+        e.message || e.detail || (typeof e.error === "string" ? e.error : null) || `the workflow runner returned HTTP ${res.status}`
+      );
+      werr.status = res.status;
+      throw werr;
+    }
+    // Liberal accept: a plain-JSON reply (no stream) is decoded as the complete result.
+    const ct = res.headers && typeof res.headers.get === "function" ? res.headers.get("content-type") || "" : "";
+    if (ct.includes("json")) {
+      let body = null;
+      try {
+        body = await res.json();
+      } catch {
+        body = null;
+      }
+      return { slug: m.slug, steps: [], complete: body && typeof body === "object" ? body : null, events: [] };
+    }
+    // The SSE stream: split records on blank lines (CRLF-safe), decode each.
+    const events = [];
+    const decoder = new TextDecoder("utf-8");
+    let buf = "";
+    const drain = () => {
+      buf = buf.replace(/\r\n/g, "\n");
+      let i;
+      while ((i = buf.indexOf("\n\n")) !== -1) {
+        const rec = buf.slice(0, i);
+        buf = buf.slice(i + 2);
+        if (rec.trim() !== "") events.push(parseSseRecord(rec));
+      }
+    };
+    for await (const chunk of res.body) {
+      buf += decoder.decode(chunk, { stream: true });
+      drain();
+    }
+    buf += decoder.decode();
+    drain();
+    if (buf.trim() !== "") events.push(parseSseRecord(buf));
+    const steps = events.filter((ev) => ev.event === "step").map((ev) => ev.data);
+    const completeEv = events.findLast((ev) => ev.event === "complete");
+    const complete = completeEv && completeEv.data && typeof completeEv.data === "object" ? completeEv.data : null;
+    const errEv = events.find((ev) => ev.event === "error");
+    if (errEv && !complete) {
+      const d = errEv.data && typeof errEv.data === "object" ? errEv.data : { detail: String(errEv.data || "") };
+      const werr = new WhisperError(d.message || d.detail || (typeof d.error === "string" ? d.error : null) || `graph.${m.name} failed on the workflow runner`);
+      werr.events = events;
+      throw werr;
+    }
+    if (!complete && steps.length === 0) {
+      const werr = new WhisperError(`graph.${m.name}: the flow stream ended without a step or complete event`);
+      werr.events = events;
+      throw werr;
+    }
+    return { slug: m.slug, steps, complete, events };
+  } catch (err) {
+    if (err instanceof WhisperError) throw err;
+    if ((err && err.name === "AbortError") || ctrl.signal.aborted) {
+      throw new WhisperError(`graph.${m.name} timed out after ${timeout}ms (flows are multi-step; raise { timeout } if you need longer)`);
+    }
+    throw new WhisperError(`graph.${m.name} failed while streaming from the workflow runner: ${err && err.message ? err.message : err}`);
+  } finally {
+    clearTimeout(t);
+  }
+}
+
+// The map-call write (whisper.submit): each payload field becomes one entry of a Cypher
+// map with its value bound as its own $-parameter (injection-safe), keys in SORTED order
+// so the query is byte-stable. Field names are accepted in both catalog spellings
+// (camelCase id or snake_case paramName) and normalised to the wire form; any extra key
+// must be a plain identifier, and the server validates the full set per kind.
+function makeMapCall(m) {
+  const canon = new Map();
+  for (const [id, param] of m.fields) {
+    canon.set(id, param);
+    canon.set(param, param);
+  }
+  return async (payload, opts = {}) => {
+    const p = payload && typeof payload === "object" && !Array.isArray(payload) ? payload : {};
+    const bound = {};
+    for (const [k, v] of Object.entries(p)) {
+      if (v === undefined) continue;
+      const name = canon.get(k) || k;
+      if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(name)) {
+        throw new WhisperError(`graph.${m.name}() field ${JSON.stringify(k)} is not a valid field name (letters, digits, _)`);
+      }
+      bound[name] = v;
+    }
+    for (const req of m.requires) {
+      if (bound[req] === null || bound[req] === undefined || String(bound[req]).trim() === "") {
+        throw new WhisperError(`graph.${m.name}() needs a { ${req} } of 'indicator' or 'feedback' (plus its fields)`);
+      }
+    }
+    const keys = Object.keys(bound).sort();
+    const cypher = `CALL ${m.proc}({` + keys.map((k) => `${k}:$${k}`).join(", ") + "})";
+    return callGraph(cypher, bound, opts, m.name);
   };
 }
 
+// Build the namespace from the generated catalog table: query + one method per entry.
+// Direct methods run their catalog Cypher; the map-call write builds its parameter map;
+// flow methods execute on the workflow runner. Every method carries its canonical docs
+// URL as `.docs` (docsBase + the entry's docPath).
+const graph = { query: graphQuery };
+graph.query.docs = GRAPH_DOCS_BASE + "/docs/cypher-api";
+
+for (const m of GRAPH_METHODS) {
+  if (m.mode === "flow") {
+    graph[m.name] = async (input, opts = {}) => callFlow(m, input, opts);
+  } else if (m.fields) {
+    graph[m.name] = makeMapCall(m);
+  } else if (m.input) {
+    graph[m.name] = async (value, opts = {}) => callGraph(m.cypher, { [m.input]: graphValue(m.name, value) }, opts, m.name);
+  } else {
+    graph[m.name] = async (opts = {}) => callGraph(m.cypher, {}, opts, m.name);
+  }
+  graph[m.name].docs = m.docs;
+}
+
 export { graph };

package/package.json

@@ -1,16 +1,42 @@
 {
   "name": "whisper-id",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "A routable Whisper IPv6 identity and safe egress for any Node agent.",
   "type": "module",
-  "exports": { ".": { "types": "./index.d.ts", "import": "./index.js" } },
+  "exports": {
+    ".": {
+      "types": "./index.d.ts",
+      "import": "./index.js"
+    }
+  },
   "types": "./index.d.ts",
-  "files": ["index.js", "index.d.ts", "README.md", "LICENSE"],
-  "engines": { "node": ">=18" },
-  "scripts": { "test": "node --test" },
-  "keywords": ["whisper", "agent", "identity", "ipv6", "egress", "proxy", "dns"],
+  "files": [
+    "index.js",
+    "index.d.ts",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "test": "node --test",
+    "gen": "node scripts/gen-graph.mjs"
+  },
+  "keywords": [
+    "whisper",
+    "agent",
+    "identity",
+    "ipv6",
+    "egress",
+    "proxy",
+    "dns"
+  ],
   "homepage": "https://whisper.online",
-  "repository": { "type": "git", "url": "https://github.com/whisper-sec/whisper-node.git" },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/whisper-sec/whisper-node.git"
+  },
   "license": "MIT",
   "author": "Whisper Security"
 }