@anokye-labs/kbexplorer-engine 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,1396 @@
+import { KBGraph, KBNode, Cluster, KnownEdgeType, EdgeType, KBEdge, KBConfig, SourceConfig, DisplayMode, Connection, NodeSourceFile, KBAccessLabel, ExternalProviderConfig } from '@anokye-labs/kbexplorer-core';
+import { C as ContentModelSchema, D as Diagnostic, K as KindConvention, a as ContentModelSource, V as VocabularyOverlay, N as NodeLayer, G as GHIssue, E as EngineEnv, b as GHTreeItem, c as GHRelease, R as RepoSource, d as RepoData } from './repo-data-0JvFdLGv.js';
+export { e as CompositeLeg, f as Conventions, g as DerivedRule, h as DiagnosticLevel, i as EdgeRule, j as EdgesSpec, F as FkFlavor, k as GHCommit, J as JsonLdContext, L as Lifecycle, l as LifecycleBand, m as NodeTypeDefinition, O as OrgDef, T as TeamOps, n as Vocabulary, o as getRegisteredTypes, p as hasType, r as registerBuiltInNodeTypes, q as registerType, s as resetNodeTypeRegistry, t as resolveNodeLayer, u as resolveType, v as resolveTypeCluster } from './repo-data-0JvFdLGv.js';
+import { C as CacheStore, R as RepoManifest } from './build-manifest-BT0sY84J.js';
+export { B as BuildManifestOptions, G as GHFileContent, b as buildManifest, f as fetchCommits, a as fetchFile, c as fetchFiles, d as fetchIssues, e as fetchPullRequests, g as fetchReleases, h as fetchTree } from './build-manifest-BT0sY84J.js';
+import { G as GraphProvider, P as ProviderResult, a as ProviderRegistry, T as TransformContext, b as GraphTransform, S as SqliteByteStore } from './sqlite-runtime-CysPjjzX.js';
+export { D as DEFAULT_TRANSFORMS, c as applyTransforms, i as issueDirectoryLinkTransform, d as issueSplitTransform, r as readmeTransform } from './sqlite-runtime-CysPjjzX.js';
+import { IngestedNode } from '@anokye-labs/kbexplorer-provider-rich-markdown/lib';
+import 'sql.js';
+
+/**
+ * Graph engine: computes the knowledge graph from parsed nodes.
+ * Builds edges, clusters, related nodes, and layout positions.
+ */
+
+/**
+ * Build the full knowledge graph from a list of nodes and cluster definitions.
+ *
+ * Access render-gate (#445): nodes whose access label marks them
+ * restricted/confidential (or explicitly unknown, or `visibility: private`)
+ * are withheld here — the single assembly choke point — so they never reach
+ * the network render, reading views, search index, or exports. Edges to a
+ * withheld node drop with it (`buildEdges` only emits edges whose target is
+ * in the node map). Unlabeled nodes are untouched.
+ */
+declare function buildGraph(nodes: KBNode[], clusters: Cluster[]): KBGraph;
+/** Get the degree (connection count) of each node. */
+declare function getNodeDegrees(graph: KBGraph): Map<string, number>;
+/** Find the hub node — prefer 'home', then 'readme', then 'overview', then most-connected. */
+declare function getHubNodeId(graph: KBGraph): string | null;
+/** Find the edge description between two nodes. */
+declare function getEdgeDescription(graph: KBGraph, from: string, to: string): string | undefined;
+/** Hard visibility limits for the rendered graph. */
+declare const MAX_VISIBLE_NODES = 40;
+declare const MAX_VISIBLE_EDGES = 80;
+interface TrimResult {
+    graph: KBGraph;
+    trimmed: boolean;
+    totalNodes: number;
+    totalEdges: number;
+}
+/**
+ * Cap graph to MAX_VISIBLE_NODES / MAX_VISIBLE_EDGES.
+ * Selection strategy:
+ * 1. Always keep the hub node and current node
+ * 2. Reserve 1-hop neighbors of the current node
+ * 3. Ensure at least 1 node per cluster (cluster floor)
+ * 4. Fill remaining slots by degree (most connected first)
+ * 5. After node trim, cap edges — prefer current-node edges, then by weight
+ */
+declare function trimGraphToLimits(graph: KBGraph, currentNodeId?: string | null, maxNodes?: number, maxEdges?: number): TrimResult;
+
+/**
+ * Edge-type weight table + lookup — governs relevance ranking for
+ * `computeRelated` (in `./graph`) and default edge weights when a connection
+ * doesn't specify its own.
+ *
+ * Provenance note (slice 1/5, anokye-labs/kbexplorer-template#472): in
+ * kbexplorer-template this pure data + lookup function live inside
+ * `src/representation/styles.ts` alongside DOM-touching style helpers (one
+ * reads the live DOM's computed style), so that whole module can't move
+ * into this runtime-agnostic engine package. These two exports are
+ * extracted here **verbatim** (byte-identical values/logic, no behavior
+ * change) since `graph.ts` — a slice-1 module — depends on them at runtime.
+ * `representation/styles.ts` itself stays in template for now (its
+ * DOM-dependent parts are out of scope for every slice of this migration so
+ * far); flagged upstream in case the template side wants to re-export from
+ * here instead of keeping a duplicate copy.
+ */
+declare const EDGE_TYPE_WEIGHTS: Record<KnownEdgeType, number>;
+/** Resolve the layout weight for an edge type (open-safe). */
+declare function getEdgeWeight(type: EdgeType | undefined): number;
+
+/**
+ * Scriptable graph-query helpers (anokye-labs/kbexplorer-template#475).
+ *
+ * A small, pure, runtime-agnostic read API over a computed {@link KBGraph}.
+ * These helpers are the scripting surface: given a graph (from
+ * {@link loadKnowledgeBase} or {@link buildGraph}) they answer the common
+ * questions — "get this node", "find nodes matching X", "who are its
+ * neighbors", "what's related", "give me a neighborhood subgraph", "what's the
+ * shortest path" — without any DOM, environment, or provider dependency.
+ *
+ * They deliberately *reuse* the graph's existing indices rather than
+ * recomputing structure: {@link related} reads the precomputed
+ * `graph.related` map, and callers who need node degrees should use
+ * {@link getNodeDegrees} from `./graph` (this module never reimplements it).
+ * The only structure built here is a lightweight, per-call adjacency map for
+ * neighbor/path traversal, which the graph does not otherwise expose.
+ */
+
+/** Traversal direction over the directed edge set. */
+type Direction = 'out' | 'in' | 'both';
+/** Options for {@link neighbors}. */
+interface NeighborOptions {
+    /** Which edge directions to follow. Default `'both'`. */
+    direction?: Direction;
+    /** Restrict to one or more edge types (e.g. `'contains'`). Default: any type. */
+    edgeType?: EdgeType | EdgeType[];
+}
+/** Options for {@link subgraph}. */
+interface SubgraphOptions {
+    /** How many hops to expand out from the seed(s). Default `1`. */
+    radius?: number;
+    /** Which edge directions to follow while expanding. Default `'both'`. */
+    direction?: Direction;
+}
+/** Options for {@link shortestPath}. */
+interface ShortestPathOptions {
+    /** Which edge directions to follow. Default `'both'`. */
+    direction?: Direction;
+}
+/** Look up a single node by id. Returns `undefined` when absent. */
+declare function getNode(graph: KBGraph, id: string): KBNode | undefined;
+/**
+ * Return every node the predicate accepts, in graph order. The predicate
+ * receives each {@link KBNode} and returns whether to keep it.
+ */
+declare function findNodes(graph: KBGraph, predicate: (node: KBNode) => boolean): KBNode[];
+/**
+ * Directly-connected neighbor nodes of `id`. Honors edge direction and an
+ * optional edge-type filter. Unknown ids yield `[]`. Neighbor ids are
+ * de-duplicated and returned in first-seen edge order; ids without a resolvable
+ * node (e.g. dangling edge targets) are skipped.
+ */
+declare function neighbors(graph: KBGraph, id: string, options?: NeighborOptions): KBNode[];
+/**
+ * Related nodes for `id`, using the graph's precomputed `related` index
+ * (weight-ranked at build time). Ids in the index that no longer resolve to a
+ * node are skipped. Unknown ids yield `[]`.
+ */
+declare function related(graph: KBGraph, id: string): KBNode[];
+/**
+ * Extract the neighborhood {@link KBGraph} around one or more seed nodes,
+ * expanded `radius` hops. The result is a well-formed graph: `nodes` are the
+ * reachable set, `edges` are only those whose endpoints are both kept,
+ * `clusters` are filtered to those actually used, and `related` is rebuilt to
+ * reference only kept nodes. Unknown seeds contribute nothing.
+ */
+declare function subgraph(graph: KBGraph, seeds: string | string[], options?: SubgraphOptions): KBGraph;
+/**
+ * Breadth-first shortest path between two node ids, returned as the inclusive
+ * list of node ids from `from` to `to` (length 1 when `from === to`). Returns
+ * `null` when either endpoint is unknown or no path exists. `direction`
+ * controls how edges may be traversed.
+ */
+declare function shortestPath(graph: KBGraph, from: string, to: string, options?: ShortestPathOptions): string[] | null;
+
+/** Canonical schema-file locations relative to the content-model root. */
+declare const SCHEMA_PATHS: {
+    readonly teamops: "teamops.yaml";
+    readonly conventions: "schema/conventions.yaml";
+    readonly edges: "schema/edges.yaml";
+    readonly lifecycle: "schema/lifecycle.yaml";
+    readonly context: "index/context.jsonld";
+    /**
+     * Optional cross-repo vocabulary / synonym overlay (#153): a JSON-LD
+     * `@context` mapping per-repo alias terms → a canonical kind. Absent in most
+     * repos, in which case the synonym layer is a safe no-op.
+     */
+    readonly vocabulary: "index/vocabulary.jsonld";
+};
+/**
+ * A content-model source is "present" iff the identity anchor (`teamops.yaml`)
+ * and the URN context (`index/context.jsonld`) both exist. When absent the
+ * provider must be a no-op so existing graphs are unchanged.
+ */
+declare function hasContentModelSource(source: ContentModelSource | null | undefined): boolean;
+/**
+ * Resolve an entity's declared term (`@type`) to its canonical kind via the
+ * cross-repo vocabulary. Returns the term unchanged when no alias is declared,
+ * so the layer is a **safe no-op** (output byte-identical to a build without it).
+ *
+ * Resolution is a single hop: a canonical target is expected to itself be a
+ * declared kind/CURIE prefix (not another alias).
+ */
+declare function canonicalKind(schema: ContentModelSchema, term: string): string;
+/**
+ * Read and parse all schema files from a content-model source.
+ * Always returns a schema (best-effort) plus any diagnostics encountered.
+ *
+ * An optional cross-repo {@link VocabularyOverlay} (#153) is merged on top of
+ * the repo's own `index/vocabulary.jsonld`. The overlay is the **shared layer
+ * supplied independently of any single repo's context**; when its terms collide
+ * with the repo-local file the overlay wins. With neither present the vocabulary
+ * is empty and the synonym layer is a safe no-op.
+ */
+declare function readContentModelSchema(source: ContentModelSource, overlay?: VocabularyOverlay): {
+    schema: ContentModelSchema;
+    diagnostics: Diagnostic[];
+};
+/** Whether a kind is org-scoped (carries an `/{org}` URN segment). */
+declare function isOrgScoped(schema: ContentModelSchema, kind: string): boolean;
+/**
+ * Derive the local/display node id for a canonical content-model URN.
+ *
+ * Content-model nodes carry TWO distinct identifiers (#445 / AF-003):
+ *  - `identity` — the canonical URN minted by {@link buildUrn} from the JSON-LD
+ *    context (e.g. `kg://xbox.com/people/ada`), the cross-provider merge key;
+ *  - `id` — this provider-local display key, derived deterministically from the
+ *    URN by stripping its `<scheme>://` prefix (e.g. `xbox.com/people/ada`).
+ *
+ * The mapping is a pure 1:1 function of the URN, so any consumer (viewers,
+ * link resolution) can recover a node's graph id from a resolved URN without
+ * access to the node set. Delegates to core's `stripScheme` (idempotent when
+ * no scheme is present).
+ */
+declare function urnLocalId(urn: string): string;
+/**
+ * Build a canonical URN for an entity.
+ *
+ * The URN **base** is read from the JSON-LD context (never hardcoded). For
+ * org-scoped kinds the org segment is spliced in after the base, defaulting to
+ * the home org from `teamops.yaml`:
+ *
+ *   org-scoped:        `{base}{org}/{id}`   → `kg://xbox.com/squads/personalization/game-assist`
+ *   authority-scoped:  `{base}{id}`         → `kg://xbox.com/people/ada`
+ *
+ * Returns `null` (and pushes a diagnostic) when the kind has no context prefix.
+ */
+declare function buildUrn(schema: ContentModelSchema, kind: string, id: string, org?: string, diagnostics?: Diagnostic[]): string | null;
+/**
+ * Resolve a CURIE (`prefix:local`) to a URN. Already-expanded URNs (containing
+ * `://`) are returned unchanged. Org-scoped prefixes use the optional `org`
+ * (defaulting to the home org).
+ *
+ * @example resolveCurie(schema, 'squad:game-assist') // kg://xbox.com/squads/personalization/game-assist
+ */
+declare function resolveCurie(schema: ContentModelSchema, curie: string, opts?: {
+    org?: string;
+    diagnostics?: Diagnostic[];
+}): string | null;
+/** Look up the lifecycle band a kind belongs to (e.g. `mission` → `per-cycle`). */
+declare function lifecycleBand(schema: ContentModelSchema, kind: string): string | undefined;
+/** Get the storage convention for a kind. */
+declare function getConvention(schema: ContentModelSchema, kind: string): KindConvention | undefined;
+
+/** Provider id under which content-model nodes are emitted. */
+declare const CONTENT_MODEL_PROVIDER = "content-model";
+/** Result of a content-model build. */
+interface ContentModelGraph {
+    nodes: KBNode[];
+    edges: KBEdge[];
+    diagnostics: Diagnostic[];
+}
+/**
+ * Build the content-model graph from a source. Returns empty results (a safe
+ * no-op) when no content-model source is present.
+ *
+ * An optional cross-repo {@link VocabularyOverlay} (#153) — a shared synonym
+ * layer supplied independently of any single repo's context — is merged on top
+ * of the source's own `index/vocabulary.jsonld` so repos using different words
+ * for the same concept unify to one canonical kind.
+ */
+declare function buildContentModel(source: ContentModelSource | null | undefined, vocabularyOverlay?: VocabularyOverlay): ContentModelGraph;
+
+/**
+ * Content-model registration hook (F2 / T2.5 + T2.6 — issues #164, #165).
+ *
+ * Registers the spine node types (Person, Squad, Workstream, Mission, Priority,
+ * Cycle, Org) in the node-type registry and binds each to its bespoke viewer in
+ * the viewer registry. Both registries are open seams, so this adds the kinds
+ * without touching any core union or render switch.
+ *
+ * Idempotent: registering the same id twice replaces the prior entry.
+ */
+
+interface SpineKind {
+    id: string;
+    label: string;
+    layer: NodeLayer;
+    relations: string[];
+    viewer: string;
+    description: string;
+}
+/** The content-model spine kinds and the viewer each resolves to. */
+declare const CONTENT_MODEL_KINDS: SpineKind[];
+/** Register every spine node type + its bespoke viewer name. Idempotent. */
+declare function registerContentModelTypes(): void;
+
+declare function parseMarkdownFile(path: string, raw: string): KBNode;
+/** Load authored content from a content directory in the repo. */
+declare function loadAuthoredContent(source: SourceConfig, contentPath: string, env?: EngineEnv, cache?: CacheStore): Promise<KBNode[]>;
+/** Extract issue cross-references (#N) from body text. */
+declare function extractIssueRefs(body: string | null): number[];
+/**
+ * Options for {@link issueToNode}. When `knownNumbers` is provided, only `#N`
+ * references that resolve to an existing issue or pull request emit an edge —
+ * this kills the phantom cross-reference edges that otherwise inflate the
+ * graph by hundreds of dangling targets (#NNN refs to PRs/issues that don't
+ * exist in this manifest).
+ */
+interface IssueToNodeOptions {
+    /** Set of valid issue numbers in this repo (for filtering #N cross-refs). */
+    knownIssueNumbers?: Set<number>;
+    /** Set of valid PR numbers in this repo (for filtering #N cross-refs). */
+    knownPrNumbers?: Set<number>;
+    /** Repository node id — issue is linked to this with a `tracked-in` edge. */
+    repoNodeId?: string;
+}
+declare function issueToNode(issue: GHIssue, options?: IssueToNodeOptions): KBNode;
+/** Split a markdown file into parent + section nodes at ## headings. */
+declare function splitIntoSections(parentId: string, parentTitle: string, rawContent: string, cluster: string, emoji: string, source: KBNode['source'], allNodes: KBNode[]): KBNode[];
+/** Build nodes from the file tree: repo root + directories + key files. */
+declare function treeToNodes(tree: GHTreeItem[], repoName: string, excludePaths?: string[]): KBNode[];
+/** Load repo-aware content: issues, README, and directory structure. */
+declare function loadRepoContent(source: SourceConfig, env?: EngineEnv, cache?: CacheStore): Promise<KBNode[]>;
+/** Extract cluster definitions from nodes + config. */
+declare function extractClusters(nodes: KBNode[], config: KBConfig): Cluster[];
+/** Try to load config.yaml from the repo. Falls back to DEFAULT_CONFIG. */
+declare function loadConfig(source: SourceConfig, env?: EngineEnv, cache?: CacheStore): Promise<KBConfig>;
+
+/**
+ * Minimal, Node-safe default {@link KBConfig} used as `loadConfig`'s fallback
+ * when a repo has no `config.yaml` (or it fails to load/parse).
+ *
+ * This is kept field-for-field identical to kbexplorer-template's
+ * `DEFAULT_CONFIG` (`src/types/index.ts`), with exactly one disclosed,
+ * intentional difference: template's `title` and `source` fields are backed
+ * by a Vite build-time env-injection read (`VITE_KB_TITLE`/`VITE_KB_OWNER`/
+ * `VITE_KB_REPO`/`VITE_KB_BRANCH`/`VITE_KB_PATH`, via `resolveDefaultSource`)
+ * that this package's `tests/boundary.test.ts` forbids and that this
+ * runtime-agnostic engine package must not depend on regardless (it should
+ * run under Node as well as a Vite-bundled browser app). Both fields here use
+ * exactly the same *fallback* values template's own functions already fall
+ * back to when those env vars are unset, so a repo with no Vite env
+ * configured gets byte-identical behavior either way. Callers that need
+ * environment-driven overrides (e.g. a `VITE_KB_*`-aware host app) should
+ * apply them on top of this before/after `loadConfig` merges its own
+ * `config.yaml` values in.
+ *
+ * `src/__tests__/default-config.test.ts` asserts this stays in sync with
+ * template's `DEFAULT_CONFIG` (minus the one disclosed exception above) so
+ * future drift between the two repos is caught by CI instead of silently
+ * propagating once slice 4 wires `loadConfig` to this fallback.
+ */
+declare const DEFAULT_CONFIG: KBConfig;
+
+/**
+ * nodemap.yaml parser — reads a nodemap definition and produces KBNode[].
+ *
+ * The nodemap defines how repository files, directories, and globs map
+ * to knowledge-graph nodes.  This module is standalone: callers provide
+ * I/O callbacks so it works with both GitHub API and local filesystem.
+ */
+
+/** A single entry in nodemap.yaml */
+interface NodeMapEntry {
+    id: string;
+    title?: string;
+    emoji?: string;
+    cluster?: string;
+    display?: DisplayMode;
+    connections?: 'imports' | 'references' | Connection[];
+    exclude?: string[];
+    file?: string;
+    files?: string[];
+    glob?: string;
+    directory?: string;
+    split?: 'headings';
+    each?: 'file';
+    titleFrom?: 'filename' | 'heading';
+}
+/** Parsed nodemap.yaml */
+interface NodeMap {
+    nodes: NodeMapEntry[];
+}
+/** Resolve a relative import path against the importing file's location. */
+declare function resolveImportPath(importPath: string, fromFile: string): string;
+/** Extract relative import/require paths from source code. */
+declare function extractImportPaths(content: string, fromFile: string): string[];
+/**
+ * Load and process a nodemap.yaml file.
+ * Returns KBNode[] for all mapped entries.
+ */
+declare function loadNodeMap(nodemapRaw: string, readFile: (path: string) => Promise<string | null>, listFiles?: (pattern: string) => Promise<string[]>, listDirectory?: (dir: string) => Promise<{
+    path: string;
+    type: 'blob' | 'tree';
+    size?: number;
+}[]>): Promise<KBNode[]>;
+
+/**
+ * Identity URN helpers — canonical identifiers that link node
+ * representations across providers and layers.
+ *
+ * This module is the template's ONE identity-construction mechanism
+ * (issue #445 / AF-003): every `urn:` identity string is minted by
+ * {@link urnIdentity}, and {@link assignIdentity} is the single entry point
+ * that decides a node's identity from its {@link NodeSource}.
+ *
+ * ## Relationship to core's addressing library (`buildAddress` — AF-025)
+ *
+ * kbexplorer-core v0.3.0 ships an addressing library (`buildAddress` /
+ * `buildPersonAddress`) whose canonical form is `<scheme>://[<authority>/]<body>`
+ * — the separator is always `://`. The template's documented identity scheme
+ * (content/multi-layer-identity.md, ratified in #47) is the single-colon form
+ * `urn:<namespace>:<body>` (e.g. `urn:file:src/engine/graph.ts`). Core's
+ * `IdentityAddressingConfig` cannot reproduce that shape:
+ * `buildAddress('src/engine/graph.ts', { scheme: 'urn', authority: 'file' })`
+ * → `urn://file/src/engine/graph.ts` ≠ `urn:file:src/engine/graph.ts`.
+ * Migrating the documented values would break every persisted identity
+ * (nodemap `file:` links, goldens, downstream consumers), so — per the
+ * reconciliation contract recorded on #445 — the `urn:` shapes are preserved
+ * and ALL construction routes through the shared local minting helper below.
+ * Schema-minted addresses (content-model `kg://` URNs from `context.jsonld`)
+ * are reused verbatim via the JSON-LD `@id` (the core contract: an identity
+ * address is ALWAYS reused as a node's `@id`).
+ */
+
+/**
+ * Mint a template-scheme identity URN: `urn:<namespace>:<body>`.
+ *
+ * The single `urn:` construction point (see module header). Namespaces in use:
+ * `file`, `content`, `issue`, `pr`, `commit`, `release`, `person`,
+ * `structural`, `structured`, `external`.
+ */
+declare function urnIdentity(namespace: string, body: string | number): string;
+/**
+ * Join multiple parts into an unambiguous (injective) URN body.
+ *
+ * Each part is percent-encoded before being joined with `:`, so the separator
+ * we insert is the ONLY literal colon in the result and `%` can only originate
+ * from the encoding. Distinct part tuples therefore always produce distinct
+ * bodies. This guards composite identities such as
+ * `urn:external:<provider>:<id>` against collision when a `provider` or `id`
+ * itself contains a `:` (or `%`): without encoding, `('a', 'b:c')` and
+ * `('a:b', 'c')` both collapse to `a:b:c`, silently conflating two distinct
+ * real-world entities once the cross-provider merge machinery runs.
+ *
+ * `encodeURIComponent` leaves the unreserved set (`A–Z a–z 0–9 - _ . ! ~ * ' ( )`)
+ * untouched, so non-pathological slugs (`wikipedia-reference`, `org-ceo`,
+ * `wiki-knowledge-graph`) are unchanged and existing valid identities do not
+ * churn.
+ */
+declare function urnBody(...parts: Array<string | number>): string;
+/**
+ * Generate a canonical identity URN for a node based on its source.
+ *
+ * Coverage notes:
+ *  - `authored` — the frontmatter id doubles as the content key. Rich-Markdown
+ *    authored docs (AuthoredRichMarkdownProvider) also carry an `authored`
+ *    source, so they resolve here identically to plain authored docs and merge
+ *    with other representations of the same content.
+ *  - `structured` — registry-driven nodes. Schema-minted nodes (content-model
+ *    entities) carry their canonical address as the JSON-LD `@id`; it is reused
+ *    verbatim so the schema's addressing (`buildUrn` / `context.jsonld`) and
+ *    this mechanism cannot drift. Structured nodes without an LD address get no
+ *    identity from the source alone (their namespace is producer-scoped —
+ *    `urn:structural:` vs `urn:structured:` — so producers mint it via
+ *    {@link urnIdentity} before or instead of calling this).
+ *  - `external` — provider-scoped: `urn:external:<provider>:<node id>`.
+ *    Deterministic (provider ids derive from config). The `provider` and node
+ *    `id` parts are percent-encoded via {@link urnBody} before joining, so the
+ *    composition is injective: two distinct external (provider, id) pairs can
+ *    never collide even when a part contains the `:` separator (which would
+ *    otherwise let `('a','b:c')` and `('a:b','c')` conflate two real entities).
+ *  - `person` — the stable, source-agnostic alias when present, else the
+ *    GitHub login (back-compat: existing values used `login`).
+ *  - `section` / `branch` / `repository` / `derived` — no identity: these are
+ *    either sub-node projections or provider-local structural artifacts with
+ *    no cross-provider counterpart to merge with.
+ */
+declare function assignIdentity(node: KBNode): string | undefined;
+/** Check if two nodes share an identity. */
+declare function shareIdentity(a: KBNode, b: KBNode): boolean;
+/**
+ * Build an identity index — maps identity URNs to all node IDs that share them.
+ * Used by the view system to merge representations.
+ */
+declare function buildIdentityIndex(nodes: KBNode[]): Map<string, string[]>;
+
+type StructuredFormat = 'json' | 'yaml';
+/** A structured file handed to the mapper. */
+interface StructuredFile {
+    path: string;
+    content: string;
+}
+/** An edge the produced node should carry (mapped onto a `Connection`). */
+interface NodeMapEdgeRule {
+    /** Target node id. */
+    to: string;
+    /** Taxonomy relation (e.g. `structural`). */
+    relation?: string;
+    /** Structural edge type (defaults to `references` downstream). */
+    type?: string;
+    description?: string;
+}
+/** A single declarative mapping rule. */
+interface NodeMapRule {
+    /** Informational rule id. */
+    id?: string;
+    /** Glob(s) the file path must match (any-of). Omit to match every path. */
+    glob?: string | string[];
+    /** Top-level keys the parsed object must all contain (shape match). */
+    shape?: string[];
+    /** JSON-LD `@type` assigned to matched files. */
+    type: string;
+    /** Registry `entityType`; defaults to a slug of `type`. */
+    entityType?: string;
+    cluster?: string;
+    emoji?: string;
+    /** Dot-path into the parsed data used as the node title. */
+    titleFrom?: string;
+    /**
+     * Promote selected parsed values into the JSON-LD envelope:
+     * `{ outputProp: 'dot.path.in.data' }`. The full parsed object is always
+     * retained on `node.data` regardless, so mapping stays reversible.
+     */
+    fields?: Record<string, string>;
+    /** Edges emitted from the produced node. */
+    edges?: NodeMapEdgeRule[];
+}
+/** Parsed `structured-node-map.yaml`. */
+interface StructuredNodeMap {
+    rules: NodeMapRule[];
+}
+/** Options controlling node identity/cluster when applying a map. */
+interface ApplyOptions {
+    /** Explicit node id (overrides the path-derived default). */
+    id?: string;
+    /** Prefix for the path-derived id (default `cfg`). */
+    idPrefix?: string;
+    /** Fallback cluster when neither rule nor heuristic provides one. */
+    cluster?: string;
+}
+/** Deterministic, url-safe slug for ids. */
+declare function slugify(value: string): string;
+/**
+ * Parse a structured file's content into `{ format, data }`. Returns `null`
+ * when the content is not structured object/array data (e.g. plain prose,
+ * binary, or an empty file) — such files are not this module's concern.
+ */
+declare function parseStructuredContent(file: StructuredFile): {
+    format: StructuredFormat;
+    data: Record<string, unknown> | unknown[];
+} | null;
+/**
+ * Heuristic fallback for an UNMAPPED structured file: parse → infer a sensible
+ * `@type` from its shape → produce a typed node whose `data` retains the full
+ * parsed object (so it stays reversible). Returns `null` for non-structured
+ * content.
+ */
+declare function inferStructuredNode(file: StructuredFile, parsed?: {
+    format: StructuredFormat;
+    data: Record<string, unknown> | unknown[];
+} | null, options?: ApplyOptions): KBNode | null;
+/**
+ * Map a structured file to a typed node. A matching declarative rule wins;
+ * otherwise the heuristic fallback runs. Returns `null` only when the file is
+ * not structured object/array data.
+ */
+declare function applyStructuredNodeMap(file: StructuredFile, map: StructuredNodeMap | null | undefined, options?: ApplyOptions): KBNode | null;
+/** Parse a `structured-node-map.yaml` file into a normalised {@link StructuredNodeMap}. */
+declare function parseStructuredNodeMap(raw: string | null | undefined): StructuredNodeMap;
+/**
+ * Re-serialise the original source content from a node produced by this module.
+ * Reversibility is *semantic*: re-parsing the output yields the same object that
+ * was stored on `node.data`. The format is inferred from the node's
+ * `source.ref` extension unless overridden.
+ */
+declare function reconstructSource(node: Pick<KBNode, 'data' | 'source'>, formatOverride?: StructuredFormat): string;
+
+declare const DEFAULT_STRUCTURED_CONTENT_PATH = "content-model";
+interface StructuredContentConfig {
+    path?: string;
+}
+type EnvLike = EngineEnv;
+declare function normalizeRepoRelativeDir(raw: unknown): string | null;
+declare function resolveStructuredContentPath(config: KBConfig, env?: EnvLike): string;
+declare function hasExplicitStructuredContentPath(config: KBConfig, env?: EnvLike): boolean;
+
+/** GitHub repository coordinates needed to build deep links. */
+interface RepoCoords {
+    owner: string;
+    repo: string;
+    branch: string;
+}
+/** Resolve repo coordinates from the app config (branch defaults to `main`). */
+declare function repoCoordsFromConfig(config: Pick<KBConfig, 'source'>): RepoCoords;
+/**
+ * Whether a node exposes an editable source-of-truth file. This is the single
+ * gate for the editor affordance: nodes without a resolvable writable file
+ * (README, derived, structural, unresolved stubs…) return `false`, so the
+ * editor simply never appears for them — a safe no-op.
+ */
+declare function canEditSource(node: Pick<KBNode, 'sourceFile'>): boolean;
+/** Return a node's source-of-truth file pointer, or `null` when it has none. */
+declare function resolveSourceFile(node: Pick<KBNode, 'sourceFile'>): NodeSourceFile | null;
+/** Result of validating edited source content against its declared format. */
+type ValidationResult = {
+    ok: true;
+} | {
+    ok: false;
+    error: string;
+};
+/**
+ * Normalise newlines to `\n`. Files checked out on Windows carry CRLF while a
+ * browser `<textarea>` always emits LF, so comparisons and diffs must be
+ * newline-agnostic — otherwise a one-line edit looks like a whole-file rewrite.
+ */
+declare function normalizeNewlines(text: string): string;
+/**
+ * Validate that edited content parses as its declared format **before** any
+ * handoff, so a user never opens a PR carrying invalid YAML/JSON. Empty content
+ * is rejected (an entity file must contain content). `markdown` is accepted
+ * as always-valid (there is nothing to parse) — `canEditSource` currently only
+ * surfaces the editor for `yaml`/`json`, but accepting the full
+ * `NodeSourceFile['format']` union keeps this forward-compatible and total.
+ */
+declare function validateSourceContent(raw: string, format: NodeSourceFile['format']): ValidationResult;
+/** Encode a repo-relative path for use inside a URL path (segment-wise). */
+declare function encodeRepoPath(path: string): string;
+/**
+ * GitHub web-editor URL for an **existing** file. Opening it shows GitHub's
+ * authenticated editor for the current file; the user pastes the edited content
+ * and commits it to a new branch + PR.
+ */
+declare function buildEditUrl(coords: RepoCoords, path: string): string;
+/**
+ * GitHub create-file URL for a **new** file, pre-filled with the target path and
+ * the edited content via the `filename` + `value` query params. GitHub commits
+ * it to a new branch and offers to open a PR.
+ */
+declare function buildNewFileUrl(coords: RepoCoords, path: string, content: string): string;
+/**
+ * Pick the correct GitHub deep link for the handoff: the create-file URL
+ * (content pre-filled) when the file is new, otherwise the web-editor URL for
+ * the existing file.
+ */
+declare function buildHandoffUrl(coords: RepoCoords, path: string, content: string, exists: boolean): string;
+/**
+ * Build a git-style unified diff for the change, suitable for downloading as a
+ * `.patch`. Returns an empty string when nothing changed.
+ *
+ * Pass `isNew` for a file that does not yet exist in the repo so the patch uses
+ * the git new-file headers (`new file mode` + `--- /dev/null`); a patch with
+ * `--- a/<path>` for a non-existent file would fail to apply.
+ */
+declare function buildUnifiedDiff(path: string, oldText: string, newText: string, context?: number, isNew?: boolean): string;
+/** Suggested filename for a downloaded `.patch` (basename of the source file). */
+declare function patchFilename(path: string): string;
+/** Everything the UI needs to hand a source edit off to GitHub. */
+interface SourceEditHandoff {
+    /** Whether the edited content differs from the original. */
+    changed: boolean;
+    /** Whether the source file already exists in the repo. */
+    exists: boolean;
+    /** Primary GitHub deep link to open the change as a PR. */
+    url: string;
+    /** GitHub web-editor URL for the existing file. */
+    editUrl: string;
+    /** GitHub create-file URL pre-filled with the edited content. */
+    newFileUrl: string;
+    /** Unified diff suitable for a downloadable `.patch` (empty when unchanged). */
+    patch: string;
+    /** Suggested filename for the downloaded patch. */
+    patchName: string;
+}
+/**
+ * Assemble the full handoff for an edited source file. `exists` defaults to
+ * `true` because the editor edits files that were loaded from the repo; pass
+ * `false` for a brand-new entity so the content-pre-filled create-file URL is
+ * used as the primary link.
+ */
+declare function buildSourceEditHandoff(coords: RepoCoords, file: NodeSourceFile, newContent: string, exists?: boolean): SourceEditHandoff;
+
+/**
+ * Minimal access render-gate (#445, spec item 4) over core's hoisted access
+ * exclusion contract.
+ *
+ * This template's minimal enforcement still withholds labeled-sensitive nodes
+ * from the assembled graph and search index. We preserve one deliberate
+ * template-only difference versus core's default-safe boundary: bespoke
+ * classifications such as `bespoke-scheme` remain non-withheld, because the
+ * template's current gate only withholds the known sensitive classifications
+ * from the 0.3 label-only contract.
+ */
+
+/**
+ * True when a node's access label marks it sensitive enough to withhold from
+ * render + search. Absent label → `false` (public, unchanged).
+ */
+declare function isAccessWithheld(node: Pick<KBNode, 'access'>): boolean;
+/** Drop withheld nodes from a node list (identity when nothing is labeled). */
+declare function filterAccessWithheld(nodes: KBNode[]): KBNode[];
+/**
+ * Defensively parse an authored-frontmatter `access` value into a
+ * {@link KBAccessLabel}. Frontmatter is untrusted: only well-typed
+ * `classification` / `visibility` strings and string `labels` survive.
+ * Returns `undefined` when nothing usable is present (node stays unlabeled).
+ */
+declare function parseAccessLabel(value: unknown): KBAccessLabel | undefined;
+
+/**
+ * Render markdown to HTML with untrusted-content defenses (see module header):
+ * `marked.parse` produces HTML, which is then filtered through the allowlist
+ * sanitizer. Drop-in replacement for `marked.parse(body, { async: false })`.
+ */
+declare function renderSafeMarkdown(body: string): string;
+
+/** Convert a simple glob pattern to a RegExp for matching file paths. */
+declare function globToRegex(pattern: string): RegExp;
+
+/**
+ * Authored Provider — wraps authored-content parsing (markdown files + nodemap)
+ * into a GraphProvider so the engine can orchestrate it alongside other providers.
+ */
+
+declare class AuthoredProvider implements GraphProvider {
+    id: string;
+    name: string;
+    dependencies: string[];
+    private authoredContent;
+    private nodemapRaw?;
+    private nodemapFiles?;
+    private nodemapDirs?;
+    private listFiles?;
+    constructor(authoredContent: Record<string, string>, nodemapRaw?: string | null, nodemapFiles?: Record<string, string>, nodemapDirs?: Record<string, Array<{
+        path: string;
+        type: 'blob' | 'tree';
+        size?: number;
+    }>>, listFiles?: (pattern: string) => Promise<string[]>);
+    resolve(_config: KBConfig, _existingNodes: KBNode[]): Promise<ProviderResult>;
+}
+
+/**
+ * Adapt the package's ingested node into a template {@link KBNode} the renderer
+ * understands. Preserves connections/jsonld/sourceFile from the package and
+ * re-shapes only what the template's rich-Markdown contract requires.
+ *
+ * Identity is NOT passed through verbatim (the unreconciled pass-through was
+ * #445's AF-003 / audit finding on PR #432): the node's `id` is the stable
+ * local slug, and `identity` is assigned by the template's single mechanism
+ * (`assignIdentity` — an `authored` source resolves to `urn:content:<id>`), so
+ * a doc that opts into rich-Markdown carries exactly the identity it would
+ * have had as plain authored content and merges with other representations of
+ * the same content. The package's own `kg://` address remains available in the
+ * package output; the template does not carry two competing schemes.
+ */
+declare function adaptIngestedNode(ingested: IngestedNode): KBNode;
+declare class AuthoredRichMarkdownProvider implements GraphProvider {
+    id: string;
+    name: string;
+    dependencies: string[];
+    private authoredContent;
+    constructor(authoredContent: Record<string, string>);
+    resolve(_config: KBConfig, _existingNodes: KBNode[]): Promise<ProviderResult>;
+}
+
+/**
+ * ContentModelProvider (F2 / T2.2 + T2.4 — issues #161, #163).
+ *
+ * Wraps the schema-driven {@link buildContentModel} pipeline as a
+ * {@link GraphProvider}. Relationships are emitted as `connections` on the source
+ * nodes (the orchestrator ignores a provider's `edges` and `buildGraph` derives
+ * edges from `connections`), so the resolved edges render in the graph.
+ *
+ * **Safe no-op when no content-model source is present** — it returns no nodes,
+ * so existing graphs (this repo has no content-model source) are unchanged.
+ */
+
+declare class ContentModelProvider implements GraphProvider {
+    id: string;
+    name: string;
+    dependencies: string[];
+    private source;
+    /**
+     * Optional cross-repo synonym overlay (#153) supplied independently of the
+     * source's own files — the shared vocabulary layer. Null/absent leaves the
+     * synonym layer a safe no-op.
+     */
+    private vocabularyOverlay;
+    constructor(source: ContentModelSource | null | undefined, vocabularyOverlay?: VocabularyOverlay);
+    resolve(_config: KBConfig, _existingNodes: KBNode[]): Promise<ProviderResult>;
+}
+
+/**
+ * Files Provider — wraps treeToNodes() into a GraphProvider.
+ * Produces file-tree nodes (repo root, directories, key source files).
+ * Edges are implicit via `contains` connections on each node.
+ */
+
+declare class FilesProvider implements GraphProvider {
+    id: string;
+    name: string;
+    dependencies: string[];
+    private treeItems;
+    private repoName;
+    private excludePaths?;
+    constructor(treeItems: GHTreeItem[], repoName: string, excludePaths?: string[]);
+    resolve(_config: KBConfig, _existingNodes: KBNode[]): Promise<ProviderResult>;
+}
+
+/**
+ * OrgChartProvider — creates an organizational chart as graph nodes.
+ *
+ * Config in config.yaml:
+ *   providers:
+ *     - type: orgchart
+ *       name: Team Structure
+ *       cluster: team
+ *       options:
+ *         people:
+ *           - id: ceo
+ *             name: Jane Smith
+ *             role: CEO
+ *             reports: []
+ *           - id: vp-eng
+ *             name: John Doe
+ *             role: VP Engineering
+ *             reports: [ceo]
+ *           - id: lead-fe
+ *             name: Alice Chen
+ *             role: Frontend Lead
+ *             reports: [vp-eng]
+ *             connections: [app-shell, hud]
+ */
+
+declare class OrgChartProvider implements GraphProvider {
+    id: string;
+    name: string;
+    dependencies: string[];
+    private people;
+    private defaultCluster;
+    constructor(config: ExternalProviderConfig);
+    resolve(_config: KBConfig, _existingNodes: KBNode[]): Promise<ProviderResult>;
+}
+
+type WorkPullRequestForPerson = {
+    number: number;
+    title: string;
+    state: string;
+    html_url: string;
+    user?: {
+        login: string;
+    };
+    assignees?: Array<{
+        login: string;
+    }>;
+};
+type PersonProviderPR = WorkPullRequestForPerson;
+declare class PersonProvider implements GraphProvider {
+    id: string;
+    name: string;
+    /**
+     * Run after work so we can match existing nodes; run after content-model
+     * so we can link to descriptor people.
+     */
+    dependencies: string[];
+    private issues;
+    private pullRequests;
+    constructor(issues: GHIssue[], pullRequests: PersonProviderPR[]);
+    resolve(config: KBConfig, existingNodes: KBNode[]): Promise<ProviderResult>;
+}
+
+/**
+ * Register the structural node types + their bespoke viewers. Idempotent — safe
+ * to call on every `resolve()`.
+ */
+declare function registerStructuralTypes(): void;
+/** Parse a CODEOWNERS file into `{ pattern, owners }` rules. */
+declare function parseCodeowners(content: string): Array<{
+    pattern: string;
+    owners: string[];
+}>;
+/** Build a structural node for a single `.github` file, or `null` to skip it. */
+declare function buildStructuralFileNode(path: string, content: string, map: StructuredNodeMap, repoNodeId?: string): KBNode | null;
+declare class StructuralProvider implements GraphProvider {
+    id: string;
+    name: string;
+    dependencies: string[];
+    private readonly structuralFiles;
+    private readonly structuredNodeMapRaw;
+    private readonly repoNodeId;
+    constructor(structuralFiles?: Record<string, string>, structuredNodeMapRaw?: string | null, repoNodeId?: string);
+    resolve(_config: KBConfig, _existingNodes: KBNode[]): Promise<ProviderResult>;
+}
+
+/**
+ * WikipediaProvider — fetches Wikipedia article summaries and creates graph nodes.
+ *
+ * Config in config.yaml:
+ *   providers:
+ *     - type: wikipedia
+ *       name: Reference Articles
+ *       cluster: reference
+ *       options:
+ *         articles:
+ *           - title: Knowledge graph
+ *             connections: [graph-engine, type-system]
+ *           - title: Force-directed graph drawing
+ *             connections: [graph-network]
+ *           - title: React (software)
+ *             id: react-framework
+ */
+
+declare class WikipediaProvider implements GraphProvider {
+    id: string;
+    name: string;
+    dependencies: string[];
+    private articles;
+    private defaultCluster;
+    constructor(config: ExternalProviderConfig);
+    resolve(_config: KBConfig, _existingNodes: KBNode[]): Promise<ProviderResult>;
+}
+
+type WorkPullRequest = {
+    number: number;
+    title: string;
+    body: string;
+    state: string;
+    labels: Array<{
+        name: string;
+        color: string;
+    }>;
+    html_url: string;
+    created_at: string;
+    updated_at: string;
+    head_branch?: string;
+    /** GitHub user who opened the pull request. */
+    user?: {
+        login: string;
+    };
+};
+type WorkCommit = {
+    sha: string;
+    commit: {
+        message: string;
+        author: {
+            name: string;
+            date: string;
+        };
+    };
+    html_url: string;
+};
+type WorkRepoMetadata = {
+    name: string;
+    description: string;
+    html_url: string;
+    default_branch: string;
+    stargazers_count: number;
+    forks_count: number;
+    private: boolean;
+    topics: string[];
+    primary_language: string;
+    languages: Array<{
+        name: string;
+        size: number;
+    }>;
+    owner: {
+        login: string;
+        avatar_url: string;
+    };
+};
+declare class WorkProvider implements GraphProvider {
+    id: string;
+    name: string;
+    dependencies: string[];
+    private issues;
+    private pullRequests;
+    private commits;
+    private branches;
+    private repoMetadata;
+    private releases;
+    constructor(issues: GHIssue[], pullRequests: WorkPullRequest[], commits: WorkCommit[], branches?: Array<{
+        name: string;
+        protected: boolean;
+    }>, repoMetadata?: WorkRepoMetadata | null, releases?: GHRelease[]);
+    resolve(_config: KBConfig, _existingNodes: KBNode[]): Promise<ProviderResult>;
+}
+
+/**
+ * External provider plugin loader.
+ *
+ * Builds {@link GraphProvider} instances from the `providers` entries in
+ * config.yaml. Two resolution paths:
+ *
+ *   1. **Local / third-party module** — when an entry sets `module`, the loader
+ *      dynamic-imports that ES-module specifier and calls its default export
+ *      (a `ProviderFactory` created with `defineProvider()` from
+ *      `@anokye-labs/kbexplorer-core`). This is the headline extensibility path:
+ *      a provider can be added with no core code change. The specifier may be a
+ *      **local** relative path (`./`, `../`) or a **bare npm package** name
+ *      (`pkg`, `@scope/pkg`, `pkg/subpath`) resolved from `node_modules`;
+ *      absolute paths and URL/scheme specifiers are rejected so the loader
+ *      never executes arbitrary remote code. A third-party module is guarded
+ *      against the provider-contract version + capabilities it declares
+ *      ({@link checkProviderCompatibility}) and skipped with a clear message if
+ *      incompatible, rather than crashing the build.
+ *   2. **First-party built-in** — `wikipedia` / `orgchart` are resolved directly.
+ *
+ * Providers authored against the core contract expose a `resolve(context)`
+ * signature; the template engine runs providers as `resolve(config, existing)`.
+ * {@link adaptCoreProvider} bridges the two so a single contract serves both
+ * local modules and (later) third-party npm packages.
+ */
+
+interface LoadExternalProvidersOptions {
+    importBaseUrl?: string | URL;
+}
+/**
+ * Load external providers from config entries, in declared order. Module-backed
+ * entries are dynamic-imported; built-in types are resolved directly. The
+ * registry topo-sorts the returned providers by their `dependencies`.
+ */
+declare function loadExternalProviders(configs: ExternalProviderConfig[], options?: LoadExternalProvidersOptions): Promise<GraphProvider[]>;
+
+/**
+ * Provider orchestrator — runs registered providers in dependency order
+ * and merges their results into a unified KBGraph.
+ */
+
+/**
+ * Run all registered providers in dependency order and collect their nodes.
+ * Lower-level helper for callers that need to apply transforms before
+ * building the final graph.
+ */
+declare function collectProviderNodes(registry: ProviderRegistry, config: KBConfig): Promise<KBNode[]>;
+/**
+ * Run all registered providers in dependency order and merge their
+ * results into a unified KBGraph.
+ */
+declare function orchestrate(registry: ProviderRegistry, config: KBConfig): Promise<KBGraph>;
+/**
+ * Run providers, then the ordered post-provider transform stage, then build the
+ * final graph. This is the single assembly path shared by the local and remote
+ * loaders: they wire providers + a {@link TransformContext} and call this; all
+ * post-processing (README synthesis, issue→directory linking, issue splitting)
+ * lives in the transforms, not the loaders.
+ */
+declare function orchestrateWithTransforms(registry: ProviderRegistry, config: KBConfig, ctx: TransformContext, transforms?: readonly GraphTransform[]): Promise<KBGraph>;
+
+/**
+ * Unified knowledge-base loader (Phase 4 / F4 #318).
+ *
+ * Collapses the former local + remote loaders into a single entrypoint:
+ * `loadKnowledgeBase(source, config)`. The {@link RepoSource} abstracts *where*
+ * the data comes from (a manifest, the GitHub API, a future custom SoR); this
+ * function wires the providers from the source's {@link RepoData} bundle and
+ * runs the shared transform stage. Provider wiring is conditional on what the
+ * bundle actually carries, so each source produces byte-identical output to its
+ * former dedicated loader.
+ */
+
+/** Build + register the provider pipeline from a normalized {@link RepoData} bundle. */
+declare function registerProviders(registry: ProviderRegistry, data: RepoData): void;
+/**
+ * Load a knowledge base from any {@link RepoSource}. Single replacement for the
+ * former `loadLocalKnowledgeBase` / `loadRemoteKnowledgeBase` bodies.
+ *
+ * Two call shapes are supported (distinguished by the first argument):
+ *
+ *  1. **Positional / advanced** — `loadKnowledgeBase(source, config, env?, options?)`
+ *     returns `{ graph, config }`. This is the form the kbexplorer-template
+ *     pins by SHA and MUST remain byte-for-byte compatible.
+ *
+ *  2. **Config-first / scripting** — `loadKnowledgeBase(config, options?)`
+ *     returns the bare {@link KBGraph}. The source is taken from
+ *     `options.source` when provided, otherwise a default
+ *     {@link GitHubApiSource} is constructed from `config.source`. This is the
+ *     ergonomic entry for scripts that "just want the graph".
+ *
+ * The overload is resolved purely by argument shape: a {@link RepoSource} is an
+ * object exposing a `getRepoData()` method, whereas a {@link KBConfig} is not.
+ */
+interface LoadKnowledgeBaseOptions {
+    /**
+     * The source to load from. When omitted, a {@link GitHubApiSource} is built
+     * from `config.source`. Supply a {@link ManifestSource}, `FileSystemSource`,
+     * or any custom {@link RepoSource} to load from elsewhere.
+     */
+    source?: RepoSource;
+    /** Optional engine environment (e.g. GitHub API base) threaded to sources/store. */
+    env?: EngineEnv;
+    importBaseUrl?: string | URL;
+    graphStore?: {
+        byteStore?: SqliteByteStore;
+        locateFile?: (file: string) => string;
+    };
+}
+type PositionalOptions = {
+    importBaseUrl?: string | URL;
+    graphStore?: {
+        byteStore?: SqliteByteStore;
+        locateFile?: (file: string) => string;
+    };
+};
+declare function loadKnowledgeBase(source: RepoSource, config: KBConfig, env?: EngineEnv, options?: PositionalOptions): Promise<{
+    graph: KBGraph;
+    config: KBConfig;
+}>;
+declare function loadKnowledgeBase(config: KBConfig, options?: LoadKnowledgeBaseOptions): Promise<KBGraph>;
+
+/** Inputs `validateGraph` needs — a subset of the fields `buildManifest` already produces. */
+type GraphValidationInput = Pick<RepoManifest, 'authoredContent'> & Partial<Pick<RepoManifest, 'configRaw' | 'nodemapRaw' | 'tree' | 'issues'>>;
+type ValidationSeverity = 'error' | 'warning';
+type ValidationRule = 'broken-inline-link' | 'missing-github-link' | 'duplicate-id' | 'orphan-node' | 'invalid-cluster' | 'missing-nodemap-path' | 'empty-content';
+/** One structural finding. `severity: 'error'` gates a caller (exit non-zero); `'warning'` does not. */
+interface ValidationFinding {
+    rule: ValidationRule;
+    severity: ValidationSeverity;
+    message: string;
+    nodeId?: string;
+    target?: string;
+}
+interface GraphValidationResult {
+    /** `true` iff there are zero errors — mirrors the script's `process.exit(errors > 0 ? 1 : 0)`. Warnings never fail the gate. */
+    ok: boolean;
+    errorCount: number;
+    warningCount: number;
+    findings: ValidationFinding[];
+    summary: {
+        contentCount: number;
+        issueCount: number;
+    };
+}
+/**
+ * Validate structural integrity of the authored-content graph: dangling
+ * inline links, duplicate/orphan node ids, invalid cluster assignments,
+ * nodemap.yaml path integrity, and empty content bodies. Non-gating callers
+ * can ignore `ok`/`errorCount`; a gating CLI should exit non-zero when
+ * `!result.ok`.
+ */
+declare function validateGraph(input: GraphValidationInput): GraphValidationResult;
+
+/**
+ * `assessGraph` — non-gating quality scoring + actionable suggestions over
+ * the engine's authored-content graph, ported faithfully from kbexplorer-
+ * template's `scripts/assess-graph.js` (anokye-labs/kbexplorer-engine#18,
+ * epic anokye-labs/kbexplorer-template#463).
+ *
+ * See `./graph-analysis-shared` for why this walks the narrow inline-link
+ * graph directly instead of the fully-computed `KBGraph` from `buildGraph`.
+ */
+
+/** Inputs `assessGraph` needs — a subset of the fields `buildManifest` already produces. */
+type GraphAssessmentInput = Pick<RepoManifest, 'authoredContent'>;
+interface QualityScores {
+    connectivity: number;
+    /**
+     * Defaults to 100 ("perfect balance") when fewer than 2 clusters exist —
+     * verbatim from the script's `let clusterBalanceScore = 100` default,
+     * which is what still feeds `--gate` scoring even though the human log
+     * prints "N/A" in that case. See {@link AssessmentResult.scoreDetails}'s
+     * `clusterBalanceApplicable` for the "N/A" distinction.
+     */
+    clusterBalance: number;
+    density: number;
+    bidirectionality: number;
+    contentDepth: number;
+}
+interface GraphAssessmentConstraint {
+    value: number;
+    limit: number;
+    ok: boolean;
+}
+interface HubReachability {
+    hubId: string | null;
+    maxHops: number;
+    unreachable: string[];
+}
+interface GraphAssessmentGate {
+    pass: boolean;
+    failures: Array<{
+        metric: keyof QualityScores;
+        actual: number;
+        minimum: number;
+    }>;
+}
+interface AssessmentResult {
+    summary: {
+        nodeCount: number;
+        edgeCount: number;
+        clusterCount: number;
+    };
+    constraints: {
+        nodeCount: GraphAssessmentConstraint;
+        edgeCount: GraphAssessmentConstraint;
+        clusterCount: GraphAssessmentConstraint;
+        /** Node ids with zero incoming links — includes one entry per authored file, so a duplicated id can appear more than once (matches the script). */
+        orphanNodes: string[];
+        hubReachability: HubReachability;
+    };
+    scores: QualityScores;
+    /** The raw stats each score in {@link scores} was derived from. */
+    scoreDetails: {
+        avgLinksPerNode: number;
+        clusterSizes: number[];
+        /** `null` when fewer than 2 clusters exist (no standard deviation to report). */
+        clusterStdDev: number | null;
+        /** `true` iff 2+ clusters exist, i.e. `clusterBalance`/`clusterStdDev` reflect a real computation rather than the N/A default. */
+        clusterBalanceApplicable: boolean;
+        density: number;
+        bidirectionalPct: number;
+        avgContentLength: number;
+    };
+    suggestions: string[];
+    /** Present only when `options.gate` is requested — mirrors `node scripts/assess-graph.js --gate`. */
+    gate?: GraphAssessmentGate;
+}
+interface AssessGraphOptions {
+    /** When true, also evaluates the `--gate` minimum-score thresholds and populates {@link AssessmentResult.gate}. */
+    gate?: boolean;
+}
+/**
+ * Assess quality of the authored-content graph: readability constraints
+ * (node/edge/cluster counts, orphans, hub reachability), five 0-100 quality
+ * scores (connectivity, cluster balance, link density, bidirectionality,
+ * content depth), and actionable suggestions. Always non-gating unless the
+ * caller opts into `options.gate` and checks the returned `gate.pass`.
+ */
+declare function assessGraph(input: GraphAssessmentInput, options?: AssessGraphOptions): AssessmentResult;
+
+/**
+ * Catalogue-pipeline shapes shared by `deriveNeeds`, `compareContent`, and
+ * `enrichFromManifest` (anokye-labs/kbexplorer-engine#19, part of the
+ * thin-CLI/fat-engine epic anokye-labs/kbexplorer-template#463).
+ *
+ * These mirror the `content/catalogue.json` schema consumed by
+ * kbexplorer-template's `scripts/derive-content.js`, `scripts/compare-content.js`,
+ * and `scripts/enrich-context.js` — the kb-architect/kb-writer authoring
+ * pipeline this module ports into the engine, field for field.
+ */
+/** A single node in `content/catalogue.json`. */
+interface CatalogueNode {
+    id: string;
+    title?: string;
+    cluster?: string;
+    file?: string;
+    prompt?: string;
+    edgeHints?: string[];
+    /** Marks hand-written content that must never be regenerated. */
+    authored?: boolean;
+    /** Marks content the kb-writer agent is expected to generate/regenerate. */
+    derived?: boolean;
+    /** Catalogue nodes may carry additional fields (e.g. enrichment output); preserved as-is. */
+    [key: string]: unknown;
+}
+/** The `content/catalogue.json` file's top-level shape. */
+interface Catalogue {
+    nodes: CatalogueNode[];
+    [key: string]: unknown;
+}
+/**
+ * Raw content-file text, keyed by catalogue node `id` (i.e. the contents of
+ * `content/${id}.md`), for every content file that currently exists on disk —
+ * including files that don't correspond to any catalogue node (needed to
+ * detect orphans in {@link compareContent}). Callers own the actual file
+ * I/O (reading `content/`); these helpers only reason over what they're handed,
+ * keeping them pure and source-agnostic.
+ */
+type CatalogueContentFiles = Record<string, string>;
+
+/**
+ * `deriveNeeds` — faithful port of kbexplorer-template's
+ * `scripts/derive-content.js` (anokye-labs/kbexplorer-engine#19).
+ *
+ * Reports which `derived: true` catalogue nodes are missing authored content,
+ * so a kb-writer agent (or its thin `kbx graph derive` CLI wrapper, landing
+ * in a follow-up) knows what to generate. Pure and source-agnostic: the
+ * template script reads `content/*.md` off disk itself; this helper instead
+ * takes the already-read file contents via {@link CatalogueContentFiles} so
+ * it has no filesystem dependency of its own.
+ */
+
+/** The subset of `CatalogueNode` fields `derive-content.js --json` emits per node. */
+interface DeriveNeedsNode {
+    id: string;
+    title?: string;
+    cluster?: string;
+    file?: string;
+    prompt?: string;
+    edgeHints?: string[];
+}
+interface DeriveNeedsResult {
+    /** Total number of nodes in the catalogue. */
+    total: number;
+    /** Nodes preserved as-authored (either `authored: true`, or a `derived` node whose content file carries an `authored: true` frontmatter override). */
+    authored: number;
+    /** Nodes that still need content generation. */
+    derived: number;
+    nodes: DeriveNeedsNode[];
+}
+/**
+ * A node needs generation when it is `derived` and either has no content
+ * file yet, or its content file lacks an `authored: true` frontmatter
+ * override — matching the template script's `derived.push(...)` /
+ * `needsGeneration.push(...)` branches exactly, including the fact that
+ * `authored: true` nodes are always treated as authored regardless of
+ * whether their content file currently exists.
+ */
+declare function deriveNeeds(catalogue: Catalogue, contentFiles: CatalogueContentFiles): DeriveNeedsResult;
+
+/**
+ * `compareContent` — faithful port of kbexplorer-template's
+ * `scripts/compare-content.js` (anokye-labs/kbexplorer-engine#19).
+ *
+ * Compares the catalogue against existing content files and reports coverage
+ * (authored / derived / missing / extra) plus drift (cluster changes,
+ * link-count changes beyond a threshold of 3). Pure and source-agnostic: the
+ * template script reads `content/*.md` itself; this helper instead takes the
+ * already-read file contents via {@link CatalogueContentFiles}.
+ */
+
+interface ClusterChange {
+    id: string;
+    from: string;
+    to: string;
+}
+interface LinkCountDiff {
+    id: string;
+    catalogue: number;
+    file: number;
+}
+interface CompareContentResult {
+    totalNodes: number;
+    totalContentFiles: number;
+    /** `authored: true` nodes whose content file exists (preserved as-is). */
+    authoredNodes: CatalogueNode[];
+    /** `derived: true` nodes whose content file currently exists. */
+    derivedCurrent: CatalogueNode[];
+    /** Nodes (authored or derived) whose content file is missing. */
+    missingNodes: CatalogueNode[];
+    /** Content-file ids that exist on disk but have no matching catalogue node. */
+    extraFiles: string[];
+    clusterChanges: ClusterChange[];
+    linkDiffs: LinkCountDiff[];
+}
+/**
+ * Classifies every catalogue node against the supplied content files and
+ * reports coverage + drift, matching `scripts/compare-content.js`'s
+ * computation exactly (only its `console.log` report formatting is left out —
+ * that's the CLI's job).
+ */
+declare function compareContent(catalogue: Catalogue, contentFiles: CatalogueContentFiles): CompareContentResult;
+
+/**
+ * `enrichFromManifest` — faithful port of kbexplorer-template's
+ * `scripts/enrich-context.js` (anokye-labs/kbexplorer-engine#19).
+ *
+ * Cross-references every catalogue node with a {@link RepoManifest}'s issues,
+ * pull requests, and commits, attaching `relatedIssues` / `relatedPRs` /
+ * `recentCommits` to each node. Pure and source-agnostic: the template script
+ * reads `content/catalogue.json` and `src/generated/repo-manifest.json` off
+ * disk and writes `content/catalogue-enriched.json` itself; this helper takes
+ * the already-parsed catalogue + manifest and returns the enriched result —
+ * writing it out is the CLI's job.
+ */
+
+interface RelatedIssue {
+    number: number;
+    title: string;
+    state: string;
+    snippet: string;
+}
+interface RelatedPullRequest {
+    number: number;
+    title: string;
+    state: string;
+    snippet: string;
+}
+interface RelatedCommit {
+    sha: string | undefined;
+    message: string;
+}
+interface EnrichedCatalogueNode extends CatalogueNode {
+    relatedIssues: RelatedIssue[];
+    relatedPRs: RelatedPullRequest[];
+    recentCommits: RelatedCommit[];
+}
+interface EnrichedCatalogue {
+    nodes: EnrichedCatalogueNode[];
+    [key: string]: unknown;
+}
+interface EnrichFromManifestSummary {
+    issueCount: number;
+    prCount: number;
+    commitCount: number;
+    totalNodes: number;
+    nodesWithIssues: number;
+    nodesWithPRs: number;
+    nodesWithCommits: number;
+}
+interface EnrichFromManifestResult {
+    catalogue: EnrichedCatalogue;
+    summary: EnrichFromManifestSummary;
+}
+/**
+ * Attaches `relatedIssues` / `relatedPRs` / `recentCommits` to every
+ * catalogue node by matching its file / title / id against the manifest's
+ * issues, pull requests, and commits — matching `scripts/enrich-context.js`'s
+ * matching rules and per-node caps exactly.
+ */
+declare function enrichFromManifest(catalogue: Catalogue, manifest: RepoManifest): EnrichFromManifestResult;
+
+export { type AssessGraphOptions, type AssessmentResult, AuthoredProvider, AuthoredRichMarkdownProvider, CONTENT_MODEL_KINDS, CONTENT_MODEL_PROVIDER, CacheStore, type Catalogue, type CatalogueContentFiles, type CatalogueNode, type ClusterChange, type CompareContentResult, type ContentModelGraph, ContentModelProvider, ContentModelSchema, ContentModelSource, DEFAULT_CONFIG, DEFAULT_STRUCTURED_CONTENT_PATH, type DeriveNeedsNode, type DeriveNeedsResult, Diagnostic, type Direction, EDGE_TYPE_WEIGHTS, EngineEnv, type EnrichFromManifestResult, type EnrichFromManifestSummary, type EnrichedCatalogue, type EnrichedCatalogueNode, FilesProvider, GHIssue, GHRelease, GHTreeItem, type GraphAssessmentConstraint, type GraphAssessmentGate, type GraphAssessmentInput, GraphProvider, GraphTransform, type GraphValidationInput, type GraphValidationResult, type HubReachability, type IssueToNodeOptions, KindConvention, type LinkCountDiff, type LoadKnowledgeBaseOptions, MAX_VISIBLE_EDGES, MAX_VISIBLE_NODES, type NeighborOptions, NodeLayer, type NodeMap, type NodeMapEntry, type NodeMapRule, OrgChartProvider, PersonProvider, type PersonProviderPR, ProviderRegistry, ProviderResult, type QualityScores, type RelatedCommit, type RelatedIssue, type RelatedPullRequest, type RepoCoords, SCHEMA_PATHS, type ShortestPathOptions, type SourceEditHandoff, StructuralProvider, type StructuredContentConfig, type StructuredFile, type StructuredNodeMap, type SubgraphOptions, TransformContext, type TrimResult, type ValidationFinding, type ValidationResult, type ValidationRule, type ValidationSeverity, VocabularyOverlay, WikipediaProvider, WorkProvider, adaptIngestedNode, applyStructuredNodeMap, assessGraph, assignIdentity, buildContentModel, buildEditUrl, buildGraph, buildHandoffUrl, buildIdentityIndex, buildNewFileUrl, buildSourceEditHandoff, buildStructuralFileNode, buildUnifiedDiff, buildUrn, canEditSource, canonicalKind, collectProviderNodes, compareContent, deriveNeeds, encodeRepoPath, enrichFromManifest, extractClusters, extractImportPaths, extractIssueRefs, filterAccessWithheld, findNodes, getConvention, getEdgeDescription, getEdgeWeight, getHubNodeId, getNode, getNodeDegrees, globToRegex, hasContentModelSource, hasExplicitStructuredContentPath, inferStructuredNode, isAccessWithheld, isOrgScoped, issueToNode, lifecycleBand, loadAuthoredContent, loadConfig, loadExternalProviders, loadKnowledgeBase, loadNodeMap, loadRepoContent, neighbors, normalizeNewlines, normalizeRepoRelativeDir, orchestrate, orchestrateWithTransforms, parseAccessLabel, parseCodeowners, parseMarkdownFile, parseStructuredContent, parseStructuredNodeMap, patchFilename, readContentModelSchema, reconstructSource, registerContentModelTypes, registerProviders, registerStructuralTypes, related, renderSafeMarkdown, repoCoordsFromConfig, resolveCurie, resolveImportPath, resolveSourceFile, resolveStructuredContentPath, shareIdentity, shortestPath, slugify, splitIntoSections, subgraph, treeToNodes, trimGraphToLimits, urnBody, urnIdentity, urnLocalId, validateGraph, validateSourceContent };