@unified-product-graph/sdk 0.6.0

package/dist/logic-DriXyFKi.d.ts

@@ -0,0 +1,1480 @@
+import * as _unified_product_graph_core from '@unified-product-graph/core';
+import { UPGEdge, UPGDocument, UPGBaseNode, UPGPortfolioDocument, UPGCrossEdge, UPGEdgeType, UPGProductStage, AntiPatternInputs, PropertyDefinition } from '@unified-product-graph/core';
+
+/**
+ * Classify and (optionally) repair dangling edges in a loaded UPG document.
+ *
+ * Three classes:
+ *
+ *   - **expected**: cross-product edge with `source_product_id` /
+ *     `target_product_id` annotations. Resolves once the sibling product is
+ *     loaded; keep these in the doc.
+ *   - **suspect**: cross-product edge type (per `UPG_CROSS_EDGE_TYPES`) but
+ *     no annotation. May be a stale ref; needs operator decision.
+ *   - **corrupt**: non-cross-product edge with a missing endpoint. A genuine
+ *     integrity break, typically the product of a botched manual edit or
+ *     incomplete migration.
+ *
+ * A future change will move cross-product edges to `portfolio.cross_edges`
+ * and eliminate `expected` entirely. Until then, this classifier is the
+ * bridge: better hygiene without forcing the schema migration.
+ */
+
+type DanglingEdgeClass = 'expected' | 'suspect' | 'corrupt';
+interface DanglingEdgeRecord {
+    id: string;
+    type: string;
+    class: DanglingEdgeClass;
+    source: string;
+    target: string;
+    source_product_id?: string;
+    target_product_id?: string;
+    /** Which endpoint(s) didn't resolve. */
+    missing: Array<'source' | 'target'>;
+}
+interface DanglingEdgeReport {
+    total: number;
+    by_class: Record<DanglingEdgeClass, number>;
+    edges: DanglingEdgeRecord[];
+}
+/**
+ * Walk `edges` and pick out every edge with at least one endpoint not in
+ * `nodeIds`. Pure function — does not mutate inputs. Safe to call many times.
+ */
+declare function classifyDanglingEdges(edges: readonly UPGEdge[], nodeIds: ReadonlySet<string>): DanglingEdgeReport;
+/**
+ * Render the integrity report as the multi-line stderr message described
+ * in the acceptance criteria. Returns null when there are no dangling edges.
+ */
+declare function renderDanglingReport(report: DanglingEdgeReport, filePath: string): string | null;
+
+/**
+ * Schema-drift summary. Walks a loaded UPG document once on load and
+ * counts deviations from the canonical UPG shape, by class:
+ *
+ *   1. entity_drift:     nodes whose type ∉ UPG_TYPES (often have a
+ *                         UPG_MIGRATIONS or UPG_SPLIT_MIGRATIONS rule).
+ *   2. edge_drift:       edges whose type ∉ UPG_EDGE_CATALOG. A non-canonical
+ *                         edge type often has a UPG_EDGE_MIGRATIONS rule
+ *                         pointing at its successor; see validation.ts for the
+ *                         suggested-migration logic. Canonical edges are never
+ *                         counted, even if they still appear as `from` in a
+ *                         historical migration rule.
+ *   3. top_level_drift:  nodes with top-level keys outside UPGBaseNode.
+ *   4. lifecycle_drift:  nodes whose `status` value is not a valid phase id
+ *                         for their entity type (per `getLifecycleForType`).
+ *   5. self_referential: nodes where `source_id === id` AND
+ *                         `source_type === type`. The fields are for
+ *                         external-import round-trip; self-references are
+ *                         redundant and should be dropped.
+ *   6. property_drift:   properties on a node that should have been migrated
+ *                         (rename, drop, or lift to top-level). Powered by
+ *                         UPG_PROPERTY_MIGRATIONS once full property-migration
+ *                         coverage ships; today the count is driven by
+ *                         intra-`properties` rename rules only.
+ *
+ * Output is COUNTS ONLY. The full per-node breakdown lives in the
+ * `validate_graph` MCP tool.
+ */
+
+interface SchemaDriftSummary {
+    entity_drift: number;
+    edge_drift: number;
+    top_level_drift: number;
+    lifecycle_drift: number;
+    self_referential: number;
+    property_drift: number;
+    total_nodes: number;
+    total_edges: number;
+}
+declare function computeSchemaDriftSummary(doc: UPGDocument): SchemaDriftSummary;
+declare function renderDriftSummary(summary: SchemaDriftSummary, filePath?: string): string | null;
+
+interface QuarantinedEntity {
+    id: string;
+    type: string;
+    title: string;
+    reason: string;
+}
+interface IntegrityReport {
+    /** Whether the file was modified outside the MCP server */
+    tampered: boolean;
+    /** Entities that failed schema validation after external modification */
+    quarantined: QuarantinedEntity[];
+    /** Edges removed because they reference quarantined or missing nodes */
+    orphanedEdges: number;
+}
+interface ChangeEntry {
+    action: 'create' | 'update' | 'delete';
+    entity: 'node' | 'edge';
+    id: string;
+    type: string;
+    title?: string;
+    timestamp: string;
+}
+interface MergeResult {
+    merged: boolean;
+    nodesAdded: number;
+    edgesAdded: number;
+    nodesFromDisk: number;
+    edgesFromDisk: number;
+    conflicts: Array<{
+        nodeId: string;
+        field: string;
+        ours: unknown;
+        theirs: unknown;
+    }>;
+}
+declare class UPGFileStore {
+    private doc;
+    private filePath;
+    private dirty;
+    private saveTimer;
+    private selfWriteInProgress;
+    private watcher;
+    private nodeMap;
+    private edgeMap;
+    private edgesByNode;
+    private changeLog;
+    private contentHash;
+    private baselineFileHash;
+    private baselineNodeIds;
+    private baselineEdgeIds;
+    private lastMergeResult;
+    private lastIntegrityReport;
+    private knownTypes;
+    private lastDanglingReport;
+    private lastDriftSummary;
+    /** Hash raw file bytes — used for baseline comparison (NOT the same as contentHash) */
+    private hashRawContent;
+    /** Compute integrity checksum over nodes + edges content (deterministic) */
+    private computeIntegrityChecksum;
+    /** Stamp the document with current integrity checksum */
+    private stampIntegrity;
+    /** Verify integrity and quarantine invalid entities if file was modified externally */
+    private verifyIntegrity;
+    getIntegrityReport(): IntegrityReport | null;
+    /** Snapshot current node/edge IDs as baseline for three-way merge */
+    private snapshotBaseline;
+    getLastMergeResult(): MergeResult | null;
+    load(filePath: string): Promise<void>;
+    /**
+     * Snapshot of the dangling-edge classification computed at load time.
+     * Returns null until `load()` has run.
+     */
+    getDanglingReport(): DanglingEdgeReport | null;
+    /**
+     * Snapshot of the schema-drift summary computed at load time.
+     * Counts only — full per-node breakdown is `validate_graph`.
+     * Returns null until `load()` has run.
+     */
+    getDriftSummary(): SchemaDriftSummary | null;
+    /**
+     * Drop edges matching the given dangling classes from the document. Used by
+     * the `repair_dangling_edges` tool with `dry_run: false`. Caller is
+     * responsible for choosing classes — this method does not protect
+     * `expected` cross-product edges by default; pass an empty array to no-op.
+     */
+    dropDanglingEdges(classes: ReadonlyArray<DanglingEdgeClass>): {
+        dropped: number;
+        remaining: DanglingEdgeReport;
+    };
+    save(): Promise<void>;
+    private mergeWithDisk;
+    flush(): Promise<void>;
+    /**
+     * Mark the store as dirty so the next `flush()` or `save()` writes to disk.
+     * Use this when an external caller mutates the document object directly (e.g.
+     * the cross-edge migration which modifies `doc.edges` in-place via
+     * `UPGPortfolioStore.migrateCrossEdgesFromDoc`).
+     */
+    markDirty(): void;
+    private scheduleSave;
+    private startWatching;
+    stopWatching(): void;
+    private rebuildIndexes;
+    private indexEdgeForNode;
+    private unindexEdgeForNode;
+    private computeHash;
+    getContentHash(): string;
+    getFilePath(): string;
+    getDocument(): UPGDocument;
+    getProduct(): _unified_product_graph_core.UPGProduct;
+    getNode(id: string): UPGBaseNode | undefined;
+    getEdge(id: string): UPGEdge | undefined;
+    getAllNodes(): UPGBaseNode[];
+    getAllEdges(): UPGEdge[];
+    getEdgesForNode(nodeId: string): UPGEdge[];
+    private logChange;
+    getChanges(since?: string): ChangeEntry[];
+    addNode(node: UPGBaseNode): void;
+    updateNode(id: string, patch: Partial<UPGBaseNode>): UPGBaseNode;
+    removeNode(id: string): {
+        node: UPGBaseNode;
+        removedEdgeIds: string[];
+    };
+    addEdge(edge: UPGEdge, skipValidation?: boolean): void;
+    removeEdge(id: string): UPGEdge;
+    migrateType(fromType: string, toType: string, defaults?: Record<string, unknown>): {
+        migratedNodes: number;
+        edgeRenames: Array<{
+            id: string;
+            from: string;
+            to: string;
+            flipped: boolean;
+        }>;
+        edgeDrops: Array<{
+            id: string;
+            from: string;
+        }>;
+    };
+    /**
+     * Exact-match rename of every edge whose `type === from` to `to`. Optionally
+     * flips `source`/`target` for each affected edge. The catalog is intentionally
+     * NOT consulted here — this is the low-level primitive backing
+     * `rename_edge_type`. Catalog awareness lives in the wrappers
+     * tracked separately.
+     *
+     * Returns the IDs of every edge that was actually mutated. The internal
+     * `edgesByNode` index is keyed by node id, so a flip does not require
+     * re-indexing — both endpoints are already tracked for the same edge id.
+     */
+    renameEdgeType(from: string, to: string, flip?: boolean): {
+        renamed: number;
+        ids: string[];
+    };
+    /**
+     * Apply every applicable rule from `UPG_EDGE_MIGRATIONS` (the v0.2.4
+     * canonical edge registry) to the loaded graph.
+     * Renames retarget the edge type; flipped renames swap source/target;
+     * dropped edges are removed entirely. Endpoint guards in the migration
+     * rules check post-migration node types — so callers should run any
+     * needed `migrateType` / `applySplit` pass on nodes BEFORE calling this.
+     *
+     * Wave 3 of the MCP edge-primitives cascade.
+     */
+    applyEdgeMigrations(fromVersion: string, toVersion: string): {
+        renamed: Array<{
+            id: string;
+            from: string;
+            to: string;
+            flipped: boolean;
+        }>;
+        dropped: Array<{
+            id: string;
+            from: string;
+        }>;
+    };
+    applyPropertyMigrations(fromVersion: string, toVersion: string): {
+        top_level_renames: Array<{
+            id: string;
+            from: string;
+            to: string;
+            value_changed: boolean;
+        }>;
+        lifted_properties: Array<{
+            id: string;
+            from_property: string;
+            to: string;
+            value_changed: boolean;
+        }>;
+        dropped_props: Array<{
+            id: string;
+            key: string;
+        }>;
+        dropped_self_referential: Array<{
+            id: string;
+            field: string;
+        }>;
+    };
+}
+interface PortfolioLoadResult {
+    /** Number of cross-product edges in the portfolio */
+    cross_edge_count: number;
+    /** Number of products listed in the portfolio */
+    product_count: number;
+    /** Path to the loaded portfolio file */
+    file_path: string;
+}
+interface CrossEdgeMigrationResult {
+    /** Cross-edges successfully migrated to portfolio format */
+    migrated: Array<{
+        id: string;
+        source: string;
+        target: string;
+        type: string;
+        source_product_id: string;
+    }>;
+    /** IDs of edges that could not be migrated (missing product context) */
+    skipped: Array<{
+        id: string;
+        reason: string;
+    }>;
+    /** Whether this was a dry run (no writes performed) */
+    dry_run: boolean;
+}
+declare class UPGPortfolioStore {
+    private doc;
+    private filePath;
+    private dirty;
+    private saveTimer;
+    /**
+     * Load an existing portfolio document from disk, or initialise an empty one
+     * at the given path if it does not exist.
+     *
+     * @param filePath Absolute path to the `.portfolio.upg` file.
+     * @param orgTitle Organisation title for newly created portfolios.
+     */
+    loadOrInit(filePath: string, orgTitle?: string): Promise<PortfolioLoadResult>;
+    /** Create a minimal valid UPGPortfolioDocument. */
+    private makeEmptyPortfolio;
+    /** Return the resolved portfolio file path, or null if not loaded. */
+    getFilePath(): string | null;
+    /** Return the loaded portfolio document, or null if not loaded. */
+    getDocument(): UPGPortfolioDocument | null;
+    /** True when a portfolio document is loaded and ready. */
+    isLoaded(): boolean;
+    /** Flush pending writes to disk. No-op if not dirty. */
+    flush(): Promise<void>;
+    /**
+     * Mark the portfolio store as dirty so the next `flush()` writes to disk.
+     * Use this when an external caller mutates the document object directly via
+     * `getDocument()` rather than going through `addCrossEdge` /
+     * `removeCrossEdge`. Mirrors `UPGFileStore.markDirty()`.
+     */
+    markDirty(): void;
+    private scheduleSave;
+    private writeToDisk;
+    /**
+     * Add a cross-product edge to the portfolio document. Both `source` and
+     * `target` must be qualified IDs (`{product_id}/{node_id}`).
+     */
+    addCrossEdge(edge: UPGCrossEdge): void;
+    /**
+     * Remove a cross-product edge by ID.
+     * @returns The removed edge, or null if not found.
+     */
+    removeCrossEdge(edgeId: string): UPGCrossEdge | null;
+    /** Return all cross-product edges. */
+    getAllCrossEdges(): UPGCrossEdge[];
+    /** Find a cross-product edge by ID. */
+    getCrossEdge(id: string): UPGCrossEdge | undefined;
+    /**
+     * Migrate inline cross-product edges from a product document into this
+     * portfolio document.
+     *
+     * **Does not flush** — caller is responsible for calling `.flush()` after
+     * inspecting the result and, for non-dry-run, also saving `sourceDoc`.
+     */
+    migrateCrossEdgesFromDoc(sourceDoc: UPGDocument, sourceProductId: string, targetProductId: string | null, dryRun: boolean): CrossEdgeMigrationResult;
+}
+
+interface EdgeAlias {
+    /** Original (often deprecated) type the caller passed */
+    from: string;
+    /** Canonical replacement resolved via @unified-product-graph/core's deprecation map */
+    to: string;
+}
+interface EdgeInferenceSuggestion {
+    source_type: string;
+    target_type: string;
+    edge_type: UPGEdgeType;
+}
+type EdgeInferenceOk = {
+    ok: true;
+    edgeType: UPGEdgeType;
+    tier: 'core' | 'extended';
+    /** Set when source and/or target were resolved via getReplacementType. */
+    aliased?: EdgeAlias[];
+    warning?: string;
+};
+type EdgeInferenceFail = {
+    ok: false;
+    reason: string;
+    /** Pairs that DO resolve in the catalog — best-effort near-misses. */
+    suggestions: EdgeInferenceSuggestion[];
+    /** Source/target after deprecation resolution, for diagnostics. */
+    resolved: {
+        source_type: string;
+        target_type: string;
+    };
+};
+type EdgeInferenceResult = EdgeInferenceOk | EdgeInferenceFail;
+/**
+ * Infers the canonical edge type for a (sourceType, targetType) pair, or
+ * reports a structured failure when neither the raw nor alias-resolved pair
+ * appears in the catalog. Never fabricates a Tier-3 string.
+ */
+declare function inferEdgeTypeWithTier(sourceType: string, targetType: string): EdgeInferenceResult;
+/**
+ * Throwing variant. Suitable for code paths where a missing canonical edge is
+ * unrecoverable (the caller intends to write an edge and has no fallback).
+ * Throws an `InferEdgeTypeError` carrying the structured failure for callers
+ * to format into MCP error responses.
+ */
+declare class InferEdgeTypeError extends Error {
+    readonly result: EdgeInferenceFail;
+    constructor(result: EdgeInferenceFail);
+}
+declare function inferEdgeType(sourceType: string, targetType: string): UPGEdgeType;
+
+/**
+ * Shared edge-type-pair validation. Single source of truth for the question:
+ * "given an edge type X, are these source/target node types what the catalog
+ * declares?"
+ *
+ * Called from every write surface that takes an explicit `type` parameter
+ * (create_edge, batch_create_edges, move_node) and from validate_graph to
+ * flag the new `edge_type_pair_drift` class.
+ *
+ * Background: the 2026-05-20 adversarial spec audit (F1) confirmed that
+ * explicit-type writes bypassed catalog cross-checking entirely. An LLM could
+ * write `persona_pursues_job` between `vision → vulnerability` and
+ * `validate_graph` would report the graph as clean. This helper closes that
+ * gap.
+ */
+interface EdgePairValidationOk {
+    valid: true;
+}
+interface EdgePairValidationFail {
+    valid: false;
+    reason: string;
+    expected: {
+        source: string;
+        target: string;
+    };
+    actual: {
+        source: string;
+        target: string;
+    };
+}
+type EdgePairValidationResult = EdgePairValidationOk | EdgePairValidationFail;
+/**
+ * Verify that an explicit edge type's source/target node types match the
+ * catalog's declared `source_type` / `target_type`. Returns `{ valid: true }`
+ * on match. On mismatch, returns a structured failure with both the catalog
+ * expectation and the actual node types so the caller can render a single
+ * clear error message.
+ *
+ * Unknown edge types (not in `UPG_EDGE_CATALOG`) return `{ valid: true }` —
+ * the legacy / non-canonical edge surface is not this helper's concern.
+ * Callers that care about catalog membership should check that upstream.
+ */
+declare function validateEdgeTypePair(edgeType: string, sourceNodeType: string, targetNodeType: string): EdgePairValidationResult;
+
+/** Generate a prefixed node ID */
+declare function nodeId(): string;
+/** Generate a prefixed edge ID */
+declare function edgeId(): string;
+/** Generate a prefixed product ID (for `doc.product.id` in new .upg files) */
+declare function productId(): string;
+
+/**
+ * Local anti-pattern input collector.
+ *
+ * Walks the loaded UPGFileStore once and builds the `AntiPatternInputs`
+ * shape consumed by `evaluateAntiPatterns` from `@unified-product-graph/core`.
+ *
+ * Cloud has its own SQL-based collector (Phase 2 at `packages/upg-cloud-server/
+ * src/lib/anti-pattern-inputs.ts`). Different stores, same output shape.
+ */
+
+/**
+ * Build the per-graph statistics consumed by `evaluateAntiPatterns`.
+ *
+ * Single linear pass over `getAllNodes()` plus one over `getAllEdges()`. No
+ * caching — the cost is bounded by graph size, and `validate_graph` is
+ * already O(nodes + edges) for schema drift.
+ *
+ * @param store The loaded UPGFileStore.
+ * @param productStage Active product stage (read from the document's
+ *   `product.stage` by the caller). Used by stage-gated anti-patterns.
+ */
+declare function collectAntiPatternInputs(store: UPGFileStore, productStage?: UPGProductStage): AntiPatternInputs;
+
+/**
+ * Shared property-type validation. Single source of truth for the question:
+ * "given a declared property in UPG_PROPERTY_SCHEMA, does the value match its
+ * declared type?"
+ *
+ * Called from every write surface that takes a `properties` parameter
+ * (create_node, update_node, batch_update_nodes) and from validate_graph to
+ * flag the new `property_type_drift` class.
+ *
+ * Background: the 2026-05-20 adversarial spec audit (F4) confirmed that
+ * declared property type violations were silently accepted — writing
+ * `metric.target_value = "not_a_number_lol"` was stored verbatim despite the
+ * schema declaring `target_value: number`. This helper closes that gap.
+ *
+ * UNDECLARED properties are out of scope for this helper. The existing
+ * unknown-properties warning (checkUnknownProperties) handles those.
+ */
+
+interface PropertyTypeViolation {
+    /** The property key with the wrong type. */
+    property: string;
+    /** The schema-declared expected type. */
+    expected_type: PropertyDefinition['type'];
+    /** The actual JavaScript typeof / shape descriptor. */
+    actual_type: string;
+    /** Free-text explanation. */
+    reason: string;
+}
+interface PropertyTypeCheckResult {
+    /** Violations against declared property types. Empty when no declared
+     *  property mismatched — independent of whether undeclared properties
+     *  exist (those are reported separately by checkUnknownProperties). */
+    violations: PropertyTypeViolation[];
+}
+/**
+ * Walk a node's properties bag and report violations against the type
+ * declared in `UPG_PROPERTY_SCHEMA`.
+ *
+ * Entity types with no registered schema are treated as fully permissive:
+ * no violations reported. Properties not present in the schema are skipped
+ * (unknown-properties is a separate concern).
+ *
+ * Null and undefined values are tolerated (not a violation). Arrays are
+ * special-cased for `string[]` schema entries.
+ */
+declare function checkPropertyTypes(entityType: string, properties: Record<string, unknown> | undefined): PropertyTypeCheckResult;
+/**
+ * Render violations as a single warning string for embedding in tool
+ * responses. Empty when there are no violations.
+ */
+declare function renderPropertyTypeWarning(entityType: string, violations: PropertyTypeViolation[]): string | undefined;
+
+/**
+ * Length / size guards for entity payloads. Soft warnings — not refusals.
+ *
+ * Background: the 2026-05-20 adversarial spec audit (F8) noted unbounded
+ * payload sizes on titles, descriptions, and property trees are a
+ * denial-of-service surface. We pick warnings (not refusals) to avoid
+ * breaking existing graphs that may already carry oversized payloads from
+ * earlier imports.
+ *
+ * Limits (deliberately generous):
+ *   - title.length > 256 → warning
+ *   - description.length > 16000 → warning
+ *   - property tree depth > 8 OR total property tree JSON size > 64KB → warning
+ */
+declare const TITLE_SOFT_LIMIT = 256;
+declare const DESCRIPTION_SOFT_LIMIT = 16000;
+declare const PROPERTY_TREE_SOFT_BYTES: number;
+declare const PROPERTY_TREE_SOFT_DEPTH = 8;
+interface LengthCheckResult {
+    warnings: string[];
+}
+/**
+ * Walk title / description / properties and return warning strings for each
+ * soft-limit breach. Empty `warnings` means everything is within limits.
+ */
+declare function checkLengthCaps(args: {
+    title?: string;
+    description?: string;
+    properties?: Record<string, unknown>;
+}): LengthCheckResult;
+
+/**
+ * Safe arithmetic expression evaluator for framework `computed_properties`.
+ *
+ * Framework expressions are simple math over property names, e.g.
+ *   `(reach * impact * confidence) / effort`
+ *   `(user_value + time_criticality + risk_reduction) / job_size`
+ *
+ * This evaluator is intentionally narrow: NO `eval`, NO `new Function`, NO
+ * named functions. The grammar is:
+ *
+ *   expr      := term (('+' | '-') term)*
+ *   term      := factor (('*' | '/' | '%') factor)*
+ *   factor    := unary ('^' factor)?
+ *   unary     := '-' unary | primary
+ *   primary   := NUMBER | IDENTIFIER | '(' expr ')'
+ *
+ * Identifiers resolve against a `Record<string, number>` passed by the caller.
+ * Missing identifiers cause a typed failure result; division/modulo by zero
+ * also fail. Callers always check `ok` before reading `value`.
+ *
+ * The evaluator is pure: no globals, no I/O, no closures over the caller's
+ * scope. Same input always produces the same output.
+ */
+type EvalResult = {
+    ok: true;
+    value: number;
+} | {
+    ok: false;
+    error: string;
+    missing?: string[];
+};
+/**
+ * Evaluate an arithmetic expression with identifiers resolved against `scope`.
+ *
+ * Returns a typed success/failure result. When the expression references
+ * identifiers absent from `scope`, the returned `missing` array lists them.
+ *
+ * @example
+ *   evaluateExpression('(a + b) * c', { a: 2, b: 3, c: 4 })
+ *   // → { ok: true, value: 20 }
+ *
+ * @example
+ *   evaluateExpression('a / b', { a: 1, b: 0 })
+ *   // → { ok: false, error: 'Division by zero ...' }
+ *
+ * @example
+ *   evaluateExpression('reach * impact', { reach: 5 })
+ *   // → { ok: false, error: 'Missing variables: impact', missing: ['impact'] }
+ */
+declare function evaluateExpression(expression: string, scope: Record<string, number>): EvalResult;
+
+/**
+ * Resolver enrichment helpers — UPG-505 and UPG-515.
+ *
+ * When the canonical resolver returns `null` for a (source_type, target_type)
+ * pair, these helpers surface what the catalog DOES know about, so the failure
+ * boundary becomes a teaching moment instead of a dead end.
+ *
+ * Three enrichments:
+ *
+ * - `buildAnchorHint(source, target)` — UPG-505: when the target's domain has
+ *   a canonical anchor entity that DIFFERS from the source, surface the
+ *   anchor + the domain's creation sequence so the author can route via the
+ *   correct entry point ("ideal_customer_profile is anchored in gtm_strategy
+ *   — create one of those first").
+ *
+ * - `buildAlternateAnchors(source, target)` — UPG-515: catalog walk for
+ *   edges where `target_type === requested_target` AND `source_type !==
+ *   requested_source`. Surfaces the OTHER sources the catalog connects to
+ *   this target. Sorted by classification: hierarchy > causal > semantic
+ *   > cross-domain. Capped at 3.
+ *
+ * - `buildAdjacentEdges(source)` — UPG-515: catalog walk for edges where
+ *   `source_type === requested_source`. Helps the author discover what they
+ *   CAN reach from this source. Capped at 3.
+ *
+ * All three are pure functions of the catalog; no graph state required.
+ */
+interface AnchorHint {
+    target_domain: string;
+    domain_anchor: string;
+    creation_sequence: readonly string[];
+    hint: string;
+}
+interface AlternateAnchor {
+    source_type: string;
+    edge_type: string;
+    hint: string;
+}
+interface AdjacentEdge {
+    source_type: string;
+    target_type: string;
+    edge_type: string;
+}
+/**
+ * UPG-505 — anchor hint.
+ *
+ * When the target type is anchored in a domain different from the source's
+ * domain, surface that anchor + the domain's creation sequence. Returns
+ * undefined when no useful hint can be constructed (target has no known
+ * domain, target's domain has no guide, or the target IS the anchor and the
+ * source is already in the same domain).
+ *
+ * The hint prose intentionally names the anchor explicitly so a first-time
+ * author reading the error sees what entity to create next.
+ */
+declare function buildAnchorHint(sourceType: string, targetType: string): AnchorHint | undefined;
+/**
+ * UPG-515 — alternate anchors.
+ *
+ * Walk `UPG_EDGE_CATALOG` for every edge whose `target_type` matches the
+ * requested target AND whose `source_type` differs from the requested source.
+ * Sort by classification rank (hierarchy → cross-domain) and cap at 3.
+ *
+ * This converts "no edge from `service` to `external_api`" into "but
+ * `bounded_context → external_api` is canonical."
+ *
+ * Deduplicates by source_type — when the catalog registers multiple edges
+ * from the same source to the same target (e.g. semantic + causal), the
+ * highest-ranked one wins.
+ */
+declare function buildAlternateAnchors(sourceType: string, targetType: string): AlternateAnchor[];
+/**
+ * UPG-515 — adjacent edges.
+ *
+ * Walk `UPG_EDGE_CATALOG` for every edge whose `source_type` matches the
+ * requested source. Surfaces what the author CAN reach from where they are
+ * standing. Sort by classification rank and cap at 3.
+ *
+ * Skips polymorphic edges (`source_type === '*'`) — those don't teach
+ * useful adjacency.
+ */
+declare function buildAdjacentEdges(sourceType: string): AdjacentEdge[];
+/**
+ * Convenience aggregator — emit every applicable enrichment block for a
+ * failed (source, target) pair. Used by `resolve_edge_for_pair` and
+ * `create_edge` / `batch_create_edges` error paths.
+ *
+ * Only includes fields that are non-empty / defined, so consumers don't
+ * have to filter undefined keys.
+ */
+declare function buildResolverHints(sourceType: string, targetType: string): {
+    anchor_hint?: AnchorHint;
+    alternate_anchors?: AlternateAnchor[];
+    adjacent_edges?: AdjacentEdge[];
+};
+
+/**
+ * Framework categories and structure patterns.
+ *
+ * Format conventions:
+ *   FrameworkCategory — broad discipline a framework belongs to. Grouped into
+ *     six clusters: Core Product (prioritization, strategy, discovery,
+ *     business_model, metrics, validation, planning, competitive); Design &
+ *     Research (design, ux_research, user_understanding, research,
+ *     accessibility, feedback_voc); Engineering & Ops (engineering, devops,
+ *     security, qa_testing, ai_ml, agentic); Growth & GTM (growth, marketing,
+ *     go_to_market, sales, pricing); Data/Legal/Ops (data_analytics,
+ *     legal_compliance, customer_success, team_process, program_mgmt);
+ *     Content/Portfolio (content, education, partnerships, localisation,
+ *     portfolio).
+ *   StructurePattern — visual topology of a framework's output:
+ *     'tree' | 'table' | 'matrix' | 'funnel' | 'collection' | 'quadrant' | 'flow'
+ */
+/** The broad domain a framework belongs to */
+type FrameworkCategory = 'prioritization' | 'strategy' | 'discovery' | 'business_model' | 'metrics' | 'validation' | 'planning' | 'competitive' | 'design' | 'ux_research' | 'user_understanding' | 'research' | 'accessibility' | 'feedback_voc' | 'engineering' | 'devops' | 'security' | 'qa_testing' | 'ai_ml' | 'agentic' | 'growth' | 'marketing' | 'go_to_market' | 'sales' | 'pricing' | 'data_analytics' | 'legal_compliance' | 'customer_success' | 'team_process' | 'program_mgmt' | 'content' | 'education' | 'partnerships' | 'localisation' | 'portfolio';
+/** The visual / topological shape a framework's structure takes */
+type StructurePattern = 'tree' | 'table' | 'matrix' | 'funnel' | 'collection' | 'quadrant' | 'flow';
+
+/**
+ * UPG v0.2 — Framework Type Definitions
+ *
+ * Frameworks are config-driven lenses that structure UPG graph data into
+ * well-known product management patterns (RICE, Lean Canvas, Opportunity
+ * Solution Tree, etc.). Each framework is declarative JSON — no code —
+ * describing four layers: data, structure, presentation, and education.
+ *
+ * To sequence multiple frameworks into a guided journey, use a
+ * `UPGWorkflow` (with `kind: 'framework'` steps) from
+ * `@unified-product-graph/core`.
+ *
+ * Zero dependencies — works in any JavaScript environment.
+ *
+ * https://unifiedproductgraph.org/spec
+ * License: MIT
+ */
+
+/** A named position within a framework's visual structure, populated by an entity type */
+interface FrameworkSlot {
+    /** Display label for this slot (e.g. "Key Partners", "Problem", "Reach") */
+    label: string;
+    /** The UPG entity type that fills this slot */
+    entityTypeId: string;
+    /** Explanation of what this slot represents in the framework */
+    description?: string;
+}
+/** Where the framework came from — attribution and licensing */
+interface FrameworkOrigin {
+    /** Whether the framework is from academia, a practitioner, the community, or original to UPG */
+    type: 'academic' | 'practitioner' | 'community' | 'custom';
+    /** Human-readable attribution (e.g. "Sean Ellis", "Marty Cagan", "Teresa Torres") */
+    attribution?: string;
+    /** Provenance narrative — how the framework came about (e.g. "Published in Business Model Generation") */
+    description?: string;
+    /** URL to the original source or publication */
+    url?: string;
+    /** Year the framework was first published or popularised */
+    year?: number;
+    /** License under which the framework definition is shared */
+    license?: string;
+}
+/** Declares which UPG entity type plays which role within a framework */
+interface FrameworkEntityTypeSpec {
+    /** The UPG entity type (must be a valid UPGEntityType) */
+    type: string;
+    /** The role this entity plays in the framework (e.g. "root", "item", "branch", "leaf", "bucket") */
+    role: string;
+    /** Minimum number of entities of this type required */
+    min_count?: number;
+    /** Maximum number of entities of this type allowed */
+    max_count?: number;
+    /** Whether to auto-create placeholder entities when the framework is applied */
+    auto_scaffold?: boolean;
+}
+/** A property that the framework requires on an entity */
+interface FrameworkPropertyRequirement {
+    /** The property key on the entity's properties object */
+    property: string;
+    /** The data type of the property value */
+    type: 'number' | 'string' | 'enum' | 'boolean' | 'assessment';
+    /** Whether the property must be filled for the framework to function */
+    required: boolean;
+    /** Default value to use when the property is not set */
+    default_value?: unknown;
+    /** Valid values when type is 'enum' */
+    enum_values?: string[];
+    /** Human-readable label for the property (shown in UI) */
+    label?: string;
+    /** Explanation of what this property represents */
+    description?: string;
+}
+/** A property whose value is computed from other properties via a math DSL */
+interface FrameworkComputedProperty {
+    /** The property key that will hold the computed result */
+    property: string;
+    /** A simple math expression referencing other properties (e.g. "(reach * impact * confidence) / effort") */
+    expression: string;
+    /** The entity type this computed property applies to */
+    entity_type: string;
+    /** Human-readable label for the computed property */
+    label?: string;
+    /** How to format the computed value in the UI */
+    format?: 'number' | 'percentage' | 'currency';
+}
+/** A fixed entity that the framework scaffolds automatically (e.g. quadrant labels, funnel stages) */
+interface FrameworkConstant {
+    /** The UPG entity type for this constant */
+    type: string;
+    /** Display title for the constant */
+    title: string;
+    /** Predefined properties for the constant entity */
+    properties: Record<string, unknown>;
+}
+/**
+ * Everything the framework needs from the graph's data layer — which entity
+ * types play which roles, which properties each type must carry under the
+ * lens, and any computed or scaffolded constants.
+ *
+ * @example
+ * // RICE — scores a feature on reach, impact, confidence, effort.
+ * const riceData: FrameworkDataSpec = {
+ *   entity_types: [
+ *     { type: 'feature', role: 'item', min_count: 1 },
+ *   ],
+ *   required_properties: {
+ *     feature: [
+ *       { property: 'reach', type: 'number', required: true, label: 'Reach' },
+ *       { property: 'impact', type: 'number', required: true, label: 'Impact' },
+ *       { property: 'confidence', type: 'number', required: true, label: 'Confidence (%)' },
+ *       { property: 'effort', type: 'number', required: true, label: 'Effort (person-weeks)' },
+ *     ],
+ *   },
+ *   computed_properties: [
+ *     {
+ *       property: 'rice_score',
+ *       entity_type: 'feature',
+ *       expression: '(reach * impact * confidence) / effort',
+ *       label: 'RICE',
+ *       format: 'number',
+ *     },
+ *   ],
+ * }
+ */
+interface FrameworkDataSpec {
+    /** The entity types that participate in this framework and their roles */
+    entity_types: FrameworkEntityTypeSpec[];
+    /**
+     * Properties required on each entity type, keyed by entity type string.
+     *
+     * **Framework-introduced properties.** A framework may declare
+     * property keys that do NOT appear in `UPG_PROPERTY_SCHEMA` for the target
+     * entity type. This is by design: frameworks are lenses that layer
+     * domain-specific fields on top of canonical entities (RICE adds
+     * `reach`/`impact`/`confidence`/`effort` to a feature; Kano adds
+     * `functional_response`/`dysfunctional_response`). These fields are NOT
+     * universal to the entity — they live inside the framework context.
+     *
+     * Consumers must read framework-introduced properties from this spec, not
+     * from `UPG_PROPERTY_SCHEMA`. Renderers merge both when displaying an
+     * entity under a framework. See `src/ARCHITECTURE.md` —
+     * "Framework Properties — Lens-Scoped Fields".
+     */
+    required_properties: Record<string, FrameworkPropertyRequirement[]>;
+    /** Properties that are derived from other properties via expressions */
+    computed_properties?: FrameworkComputedProperty[];
+    /** Fixed entities that the framework creates automatically */
+    constants?: FrameworkConstant[];
+}
+/** One level in a tree-structured framework */
+interface FrameworkLevel {
+    /** Zero-based depth in the tree (0 = root) */
+    depth: number;
+    /** Human-readable name for this level (e.g. "Outcome", "Opportunity") */
+    label: string;
+    /** Which UPG entity types can appear at this level */
+    entity_types: string[];
+    /** Explanation of what this level represents */
+    description: string;
+    /** The edge type connecting entities at this level to their parent */
+    edge_from_parent: string;
+}
+/** A cell in a matrix-structured framework */
+interface MatrixSlot {
+    /** Unique identifier for this slot */
+    id: string;
+    /** Display label for the slot */
+    label: string;
+    /** The UPG entity type placed in this slot */
+    entity_type: string;
+    /** Position within the matrix grid */
+    position: {
+        /** Zero-based row index */
+        row: number;
+        /** Zero-based column index */
+        col: number;
+        /** Number of rows this slot spans */
+        rowSpan?: number;
+        /** Number of columns this slot spans */
+        colSpan?: number;
+    };
+}
+/** A stage in a funnel-structured framework */
+interface FunnelStage {
+    /** Unique identifier for this stage */
+    id: string;
+    /** Display label for the stage */
+    label: string;
+    /** Position in the funnel (0 = top / widest) */
+    order: number;
+    /** The UPG entity type associated with this stage */
+    entity_type?: string;
+    /** The metric tracked at this stage (e.g. "visitors", "signups") */
+    metric_name?: string;
+}
+/** A logical grouping of entities within a collection-structured framework */
+interface NamedGroup {
+    /** Unique identifier for this group */
+    id: string;
+    /** Display label for the group */
+    label: string;
+    /** Explanation of what this group contains */
+    description: string;
+    /** Which UPG entity types belong to this group */
+    entity_types: string[];
+}
+/** How entities are topologically organised within the framework */
+interface FrameworkStructureSpec {
+    /** The visual / topological pattern (tree, table, matrix, etc.) */
+    pattern: StructurePattern;
+    /** Tree levels — only used when pattern is 'tree' */
+    levels?: FrameworkLevel[];
+    /** Edge types used to connect entities in this framework */
+    edge_types?: string[];
+    /** Matrix slots — only used when pattern is 'matrix' */
+    slots?: MatrixSlot[];
+    /** Funnel stages — only used when pattern is 'funnel' */
+    stages?: FunnelStage[];
+    /** Named groups — only used when pattern is 'collection' */
+    groups?: NamedGroup[];
+}
+/** A column definition for table-layout frameworks */
+interface TableColumn {
+    /** The property key to display in this column */
+    property: string;
+    /** Column header label */
+    label: string;
+    /** Column width in pixels (optional) */
+    width?: number;
+    /** Whether the column can be sorted */
+    sortable?: boolean;
+    /** How to render the cell value */
+    format?: 'number' | 'bar' | 'badge' | 'score_pill';
+}
+/**
+ * Discriminated union of all supported layout types.
+ * Each layout carries its own configuration fields.
+ *
+ * @example { type: 'tree', direction: 'TB', engine: 'elk' }
+ * @example { type: 'table', columns: [{ property: 'reach', label: 'Reach', format: 'score_pill' }] }
+ * @example { type: 'matrix', rows: 2, cols: 2, template: 'eisenhower' }
+ * @example { type: 'funnel', orientation: 'vertical' }
+ * @example { type: 'kanban', columns: ['backlog', 'in_progress', 'done'] }
+ * @example { type: 'quadrant', x_axis: 'impact', y_axis: 'effort', x_label: 'Impact', y_label: 'Effort' }
+ * @example { type: 'grid', groupBy: 'domain' }
+ * @example { type: 'flow', direction: 'LR' }
+ */
+type FrameworkLayout = {
+    type: 'tree'; /** Layout direction */
+    direction: 'TB' | 'LR'; /** Layout engine */
+    engine?: 'dagre' | 'elk';
+} | {
+    type: 'table'; /** Column definitions */
+    columns: TableColumn[];
+} | {
+    type: 'matrix'; /** Number of rows */
+    rows: number; /** Number of columns */
+    cols: number; /** Optional named template */
+    template?: string;
+} | {
+    type: 'funnel'; /** Funnel orientation */
+    orientation: 'vertical' | 'horizontal';
+} | {
+    type: 'kanban'; /** Column identifiers */
+    columns: string[];
+} | {
+    type: 'quadrant'; /** X-axis property */
+    x_axis: string; /** Y-axis property */
+    y_axis: string; /** X-axis label */
+    x_label?: string; /** Y-axis label */
+    y_label?: string;
+} | {
+    type: 'grid'; /** Property to group entities by */
+    groupBy: string;
+} | {
+    type: 'flow'; /** Flow direction */
+    direction: 'LR' | 'TB';
+};
+/** How the framework should be rendered in a UI */
+interface FrameworkPresentationSpec {
+    /** The layout strategy for rendering */
+    layout: FrameworkLayout;
+    /** Default sort order for entities */
+    sort_by?: {
+        property: string; /** Sort direction */
+        direction: 'asc' | 'desc';
+    };
+    /** Which dimension to use for colour coding */
+    colour_by?: 'type' | 'status' | 'score' | 'group' | 'custom';
+    /** Which properties to show on entity cards */
+    card_fields?: string[];
+    /** Whether tree branches can be collapsed */
+    collapsible?: boolean;
+    /** Custom colour map — keys are values of the colour_by dimension, values are CSS colours */
+    colour_map?: Record<string, string>;
+}
+/** One step in a guided walkthrough of how to use a framework */
+interface FrameworkStep {
+    /** Step order (1-based) */
+    order: number;
+    /** Human-readable instruction for this step */
+    instruction: string;
+    /** The property this step asks the user to fill */
+    property?: string;
+    /** The entity type this step focuses on */
+    entity_type?: string;
+}
+/** Educational context that helps users understand and apply the framework */
+interface FrameworkEducation {
+    /** A one-sentence explanation of what the framework does */
+    purpose: string;
+    /** The core question the framework helps answer */
+    core_question: string;
+    /** Situations where this framework is a good fit */
+    when_to_use: string[];
+    /** Situations where this framework is a poor fit */
+    when_not_to_use: string[];
+    /** URL to further reading about the framework */
+    learn_more_url?: string;
+    /** Step-by-step guided walkthrough */
+    steps?: FrameworkStep[];
+}
+/**
+ * A UPG Framework is a declarative, config-driven lens that structures
+ * UPG graph data into a well-known product management pattern.
+ *
+ * Frameworks are pure data — no code. The rendering engine reads the
+ * framework definition and produces the appropriate UI.
+ *
+ * @example
+ * // Abbreviated RICE definition — shows the layer split (data / structure
+ * // / presentation / education). Real definitions live in
+ * // `src/frameworks/definitions/`.
+ * const riceFramework: UPGFramework = {
+ *   id: 'rice-scoring',
+ *   name: 'RICE Scoring',
+ *   version: '0.1.0',
+ *   description: 'Score features on Reach, Impact, Confidence, Effort to prioritise.',
+ *   category: 'prioritisation',
+ *   origin: {
+ *     type: 'practitioner',
+ *     attribution: 'Sean McBride (Intercom)',
+ *     year: 2016,
+ *     license: 'MIT',
+ *   },
+ *   tags: ['prioritisation', 'scoring'],
+ *   data: {
+ *     entity_types: [{ type: 'feature', role: 'item', min_count: 1 }],
+ *     required_properties: {
+ *       feature: [
+ *         { property: 'reach', type: 'number', required: true },
+ *         { property: 'impact', type: 'number', required: true },
+ *         { property: 'confidence', type: 'number', required: true },
+ *         { property: 'effort', type: 'number', required: true },
+ *       ],
+ *     },
+ *   },
+ *   structure: { pattern: 'table' },
+ *   presentation: {
+ *     layout: {
+ *       type: 'table',
+ *       columns: [
+ *         { property: 'title', label: 'Feature' },
+ *         { property: 'rice_score', label: 'RICE', format: 'score_pill' },
+ *       ],
+ *     },
+ *     sort_by: { property: 'rice_score', direction: 'desc' },
+ *   },
+ *   education: {
+ *     purpose: 'Rank features by a simple weighted score.',
+ *     core_question: 'Which feature gives the most value for the least effort?',
+ *     when_to_use: ['A large backlog needs triage', 'Stakeholders argue by intuition'],
+ *     when_not_to_use: ['Strategic bets where effort is the wrong denominator'],
+ *   },
+ * }
+ */
+interface UPGFramework {
+    /** Unique identifier (kebab-case, e.g. "rice-scoring", "lean-canvas") */
+    id: string;
+    /** Human-readable name (e.g. "RICE Scoring", "Lean Canvas") */
+    name: string;
+    /** Semver version of this framework definition */
+    version: string;
+    /** One-sentence description of the framework */
+    description: string;
+    /** The broad domain this framework belongs to */
+    category: FrameworkCategory;
+    /** Attribution and licensing */
+    origin: FrameworkOrigin;
+    /** Freeform tags for filtering and discovery */
+    tags: string[];
+    /** Named positions within the framework's visual structure */
+    slots?: FrameworkSlot[];
+    /** What data the framework needs from the graph */
+    data: FrameworkDataSpec;
+    /** How entities are topologically organised */
+    structure: FrameworkStructureSpec;
+    /** How the framework should be rendered */
+    presentation: FrameworkPresentationSpec;
+    /** Educational context and guided walkthrough */
+    education: FrameworkEducation;
+    /** IDs of other frameworks this one can be composed with */
+    composable_with?: string[];
+    /** ID of a parent framework this one extends */
+    extends?: string;
+    /**
+     * The approaches this framework serves — many-to-many. Each value is a
+     * `UPGApproachId` (`'plan' | 'inspect' | 'prioritise' | 'trace' | 'reflect'`).
+     * Optional — partial coverage is by design; adding tags later is additive.
+     *
+     * Type-erased to `string[]` to avoid a circular import with
+     * `approaches/types.ts`. Conceptually `readonly UPGApproachId[]`.
+     *
+     * @see MENTAL-MODEL.md — approach × framework relationship
+     */
+    approach_ids?: readonly string[];
+}
+
+/**
+ * Approach execution helpers — pure functions powering the five approach
+ * verb tools (`plan`, `inspect`, `prioritise`, `trace`, `reflect`).
+ *
+ * Each helper consumes the live graph (via `UPGFileStore`) plus the spec
+ * catalog and emits a concrete structured projection. The verb handlers in
+ * `tools/spec.ts` are thin wrappers that validate inputs, call into here,
+ * and wrap the result in the family-resemblance envelope.
+ *
+ * Why a separate module:
+ *   - Keeps `tools/spec.ts` slim — handler authoring stays declarative.
+ *   - Lets the executors be unit-tested directly without the MCP envelope.
+ *   - Provides a clear contract: every function returns the structured
+ *     projection the verb's `signature_hint` documents.
+ */
+
+interface PrioritiseRankedRow {
+    entity_id: string;
+    /** Numeric score; null when the formula could not be evaluated. */
+    score: number | null;
+    /** Human-readable explanation: formula + substituted values or failure reason. */
+    rationale: string;
+    /** When score is null, the missing property keys that prevented evaluation. */
+    missing_properties?: string[];
+}
+interface PrioritiseExecutionResult {
+    kind: 'execution';
+    ranked: PrioritiseRankedRow[];
+    framework_used: {
+        id: string;
+        name: string;
+        category: string;
+        expression: string;
+    };
+    /** Properties the formula consumed (variable identifiers). */
+    required_properties: string[];
+}
+interface PrioritiseFallbackResult {
+    kind: 'fallback';
+    framework_used: {
+        id: string;
+        name: string;
+        category: string;
+    };
+    /** Why we couldn't execute (no computed expression, etc.). */
+    hint: string;
+}
+/**
+ * Execute a framework's first numeric `computed_properties` expression over a
+ * candidate set. Returns either ranked rows (when the framework defines an
+ * expression) or a fallback envelope (when it doesn't — caller should
+ * surface the framework's slots / classification as LLM substrate).
+ *
+ * Resolution per candidate:
+ *   - Look up the node in the store; missing nodes get `score: null` with a
+ *     "node not found" rationale.
+ *   - Resolve each identifier in the expression as a numeric property:
+ *     `node.properties[key]` (coerced via Number()). Top-level numeric fields
+ *     like `node.title` are NOT consulted — formulas address property keys.
+ *   - Evaluate via `evaluateExpression`; on success append to ranked with the
+ *     computed score; on failure record the missing variables.
+ *
+ * Sort: numeric desc, with nulls last (preserves input order among null rows).
+ */
+declare function executePrioritise(framework: UPGFramework, candidateIds: string[], store: UPGFileStore): PrioritiseExecutionResult | PrioritiseFallbackResult;
+interface MissingEntityRow {
+    entity_type: string;
+    domain: string | null;
+    /** Index in the domain guide's `creation_sequence` (lower = earlier). */
+    position_in_sequence: number;
+    /** Anchor entity type for the domain (commonly the typical parent). */
+    typical_parent_type: string | null;
+    hint: string;
+}
+interface PlanResult {
+    missing_entities: MissingEntityRow[];
+    /** Ratio of covered entity types to expected entity types. */
+    coverage_score: number;
+    /** Total expected entity types in scope. */
+    expected_count: number;
+    /** Number of expected types with at least one instance in the graph. */
+    covered_count: number;
+    /** Region narrowed to, if any. */
+    region: string | null;
+}
+/**
+ * Compute a missing-entity backlog from the graph's current coverage against
+ * the canonical creation sequences.
+ *
+ * When `region` is provided, the expected set is that region's entity
+ * memberships. When omitted, the expected set is every type listed across all
+ * domain guides' creation sequences (the union — that's the "whole-graph"
+ * planning surface).
+ *
+ * Ordering: missing entities are sorted by position in their domain's
+ * `creation_sequence` (earlier types surface first) so the agent always sees
+ * the foundational gaps before the late-stage ones.
+ */
+declare function executePlan(store: UPGFileStore, regionId?: string): PlanResult;
+interface InspectViolation {
+    severity: 'high' | 'medium' | 'low' | 'unknown';
+    kind: 'anti_pattern' | 'entity_drift' | 'edge_drift' | 'lifecycle_drift' | 'property_drift' | 'self_referential' | 'top_level_drift';
+    entity_id?: string;
+    description: string;
+    fix_hint: string;
+    /** Source id (anti-pattern id, migration via, etc.) for traceability. */
+    source?: string;
+}
+interface InspectResult {
+    violations: InspectViolation[];
+    scope: {
+        region: string | null;
+        entities: string[] | null;
+    };
+    /** Counts of violation kinds for quick triage. */
+    summary: Record<string, number>;
+}
+/**
+ * Wrap `validate_graph` + `get_anti_pattern_violations_for` into a single
+ * inspect projection: a flat, severity-ordered violations array plus a kind
+ * count map. The scope filter narrows by region (drop violations whose target
+ * type isn't in the region) or by entities (drop violations whose
+ * `target_entities` don't include any node-of-interest's type, and drift rows
+ * whose id isn't in the candidate set).
+ */
+declare function executeInspect(validateResult: ValidateGraphBody, scope: {
+    region?: string;
+    entities?: string[];
+}): InspectResult;
+interface ValidateGraphBody {
+    anti_pattern_violations?: Array<{
+        anti_pattern_id: string;
+        name: string;
+        severity: 'high' | 'medium' | 'low';
+        target_entities: string[];
+        description?: string;
+        why_it_matters?: string;
+        remediation?: string;
+    }>;
+    entity_drift?: Array<{
+        id: string;
+        type: string;
+        suggested_migration?: {
+            kind: string;
+            to?: string | string[];
+            via?: string;
+        };
+    }>;
+    edge_drift?: Array<{
+        id: string;
+        type: string;
+        source: string;
+        target: string;
+        suggested_migration?: {
+            kind: string;
+            to?: string;
+            via?: string;
+            flip?: boolean;
+        };
+    }>;
+    lifecycle_drift?: Array<{
+        id: string;
+        type: string;
+        status: string;
+        valid_phases: string[];
+    }>;
+    property_drift?: Array<{
+        id: string;
+        type: string;
+        property: string;
+        via: string;
+    }>;
+    self_referential?: Array<{
+        id: string;
+        fields: string[];
+    }>;
+    top_level_drift?: Array<{
+        id: string;
+        type: string;
+        unknown_fields: string[];
+    }>;
+}
+interface TraceTrailRow {
+    depth: number;
+    entity_id: string;
+    entity_type: string;
+    edge_type_in: string | null;
+}
+interface TraceResult {
+    trail: TraceTrailRow[];
+    reached: string[];
+    /** Set when traversal halts early — e.g. no canonical edge for a hop. */
+    error?: string;
+    /** Depth at which the trace halted, if it stopped early. */
+    halted_at_depth?: number;
+}
+/**
+ * Walk a typed path starting from `anchor`. Each step in `path` is an entity
+ * type; the walker chooses the canonical edge for the previous-type →
+ * current-type pair (via `resolveContainmentEdge`) unless `edgesOverride[i]`
+ * is set to a non-null string.
+ *
+ * Strategy is breadth-first per depth: at depth N+1 we walk every outgoing
+ * edge of the resolved type whose target node matches `path[N+1]`. The trail
+ * carries every reached node at every depth.
+ *
+ * Halts when no canonical edge can be resolved for a hop AND no override is
+ * supplied — returning a partial trail + `error` + `halted_at_depth`. This
+ * gives the caller enough signal to either supply an override or rewrite
+ * the path.
+ */
+declare function executeTrace(store: UPGFileStore, anchor: string, path: string[], edgesOverride?: (string | null)[]): TraceResult;
+type ReflectPromptKind = 'assumption' | 'alternative' | 'blind_spot' | 'load_bearing';
+interface ReflectPrompt {
+    kind: ReflectPromptKind;
+    question: string;
+    target_entities?: string[];
+}
+interface ReflectResult {
+    prompts: ReflectPrompt[];
+    mode: string | null;
+    scope: string | null;
+}
+/**
+ * Emit structured reflection prompts based on graph topology + mode.
+ *
+ * - "assumptions" — find entities of type `assumption` or drafted hypotheses;
+ *   one prompt per entity asks the author to surface evidence / falsification.
+ * - "alternatives" — find parents with multiple siblings of the same type and
+ *   prompt "did you consider…" alternatives.
+ * - "blind-spots" — find atomic domains with zero entities and prompt
+ *   the author to explain why that surface is empty.
+ * - "load-bearing" — find entities with the highest incoming-edge counts and
+ *   prompt "if this changes, what depends on it?"
+ * - No mode (open) — pick the most informative single category based on the
+ *   graph's actual state; never empty unless the graph itself is empty.
+ *
+ * Prompts are capped at a sensible per-mode limit so the response stays
+ * digestible — the agent calls again with a tighter mode if it wants more.
+ */
+declare function executeReflect(store: UPGFileStore, mode?: string, scope?: string | null): ReflectResult;
+
+/**
+ * UPG entity classification — three axes used by skills to determine
+ * relevance:
+ *
+ * 1. **Business Area**: what question does this entity help answer?
+ * 2. **Tier**: what stage of company maturity needs this?
+ * 3. **Tier Cluster**: which capability group within team/scaleup tiers?
+ *
+ * Canonical reference; import from here rather than duplicating mappings.
+ * Entity types are defined in `@unified-product-graph/core`. Use
+ * `validateClassificationCoverage()` to detect drift between the spec and
+ * this map.
+ */
+type BusinessArea = 'identity' | 'understanding' | 'discovery' | 'reaching' | 'converting' | 'building' | 'sustaining' | 'learning';
+type Tier = 'solo' | 'team' | 'scaleup' | 'enterprise';
+type TierCluster = 'team_coordination' | 'design_alignment' | 'user_signal' | 'growth_operations' | 'ecosystem_partnerships' | 'program_management';
+declare const BUSINESS_AREA_META: Record<BusinessArea, {
+    label: string;
+    question: string;
+    emoji: string;
+}>;
+declare const TIER_DESCRIPTIONS: Record<Tier, {
+    label: string;
+    description: string;
+}>;
+/** Tier entity counts — computed from ENTITY_CLASSIFICATION so they never drift */
+declare function getTierEntityCount(tier: Tier): number;
+declare const TIER_CLUSTER_META: Record<TierCluster, {
+    label: string;
+    description: string;
+    tier: Tier;
+}>;
+interface EntityClassification {
+    business_area: BusinessArea;
+    tier: Tier;
+    cluster?: TierCluster;
+}
+declare const ENTITY_CLASSIFICATION: Record<string, EntityClassification>;
+/** Get the classification for an entity type (falls back to enterprise/building for unknown types) */
+declare function getClassification(entityType: string): EntityClassification;
+/** Get all entity types assigned to a specific tier (exact match, not cumulative) */
+declare function getEntitiesForTier(tier: Tier): string[];
+/** Get all entity types assigned to a specific business area */
+declare function getEntitiesForBusinessArea(area: BusinessArea): string[];
+/** Get all entity types for a tier AND business area intersection */
+declare function getEntitiesForTierAndArea(tier: Tier, area: BusinessArea): string[];
+/** Get all entity types in a specific tier cluster */
+declare function getEntitiesForCluster(cluster: TierCluster): string[];
+/**
+ * Map a product stage to the appropriate tier.
+ * Products at earlier stages need fewer entity types.
+ */
+declare function getTierForStage(stage: string): Tier;
+/**
+ * Get all entity types available at a given tier (cumulative).
+ * solo includes only solo. team includes solo + team. etc.
+ */
+declare function getEntitiesUpToTier(tier: Tier): string[];
+/**
+ * Check whether an entity type is relevant for a given product stage.
+ * A type is relevant if its tier is at or below the tier for the stage.
+ */
+declare function isRelevantForStage(entityType: string, stage: string): boolean;
+/**
+ * Validates that ENTITY_CLASSIFICATION covers every type in @unified-product-graph/core.
+ * Run at dev time or in tests to catch drift early.
+ * Returns { missing, extra } — both should be empty for a healthy sync.
+ */
+declare function validateClassificationCoverage(): {
+    missing: string[];
+    extra: string[];
+};
+
+export { buildAlternateAnchors as $, type AdjacentEdge as A, BUSINESS_AREA_META as B, type ChangeEntry as C, DESCRIPTION_SOFT_LIMIT as D, ENTITY_CLASSIFICATION as E, type PrioritiseRankedRow as F, type PropertyTypeCheckResult as G, type PropertyTypeViolation as H, type IntegrityReport as I, type ReflectPromptKind as J, type ReflectResult as K, type LengthCheckResult as L, type MergeResult as M, TIER_DESCRIPTIONS as N, TITLE_SOFT_LIMIT as O, PROPERTY_TREE_SOFT_BYTES as P, type QuarantinedEntity as Q, type ReflectPrompt as R, type SchemaDriftSummary as S, TIER_CLUSTER_META as T, UPGFileStore as U, type Tier as V, type TierCluster as W, type TraceResult as X, type TraceTrailRow as Y, type ValidateGraphBody as Z, buildAdjacentEdges as _, UPGPortfolioStore as a, buildAnchorHint as a0, buildResolverHints as a1, checkLengthCaps as a2, checkPropertyTypes as a3, classifyDanglingEdges as a4, collectAntiPatternInputs as a5, computeSchemaDriftSummary as a6, edgeId as a7, evaluateExpression as a8, executeInspect as a9, executePlan as aa, executePrioritise as ab, executeReflect as ac, executeTrace as ad, getClassification as ae, getEntitiesForBusinessArea as af, getEntitiesForCluster as ag, getEntitiesForTier as ah, getEntitiesForTierAndArea as ai, getEntitiesUpToTier as aj, getTierEntityCount as ak, getTierForStage as al, inferEdgeType as am, inferEdgeTypeWithTier as an, isRelevantForStage as ao, nodeId as ap, productId as aq, renderDanglingReport as ar, renderDriftSummary as as, renderPropertyTypeWarning as at, validateClassificationCoverage as au, validateEdgeTypePair as av, type AlternateAnchor as b, type AnchorHint as c, type BusinessArea as d, type CrossEdgeMigrationResult as e, type DanglingEdgeClass as f, type DanglingEdgeRecord as g, type DanglingEdgeReport as h, type EdgeAlias as i, type EdgeInferenceFail as j, type EdgeInferenceOk as k, type EdgeInferenceResult as l, type EdgeInferenceSuggestion as m, type EdgePairValidationFail as n, type EdgePairValidationOk as o, type EdgePairValidationResult as p, type EvalResult as q, InferEdgeTypeError as r, type InspectResult as s, type InspectViolation as t, type MissingEntityRow as u, PROPERTY_TREE_SOFT_DEPTH as v, type PlanResult as w, type PortfolioLoadResult as x, type PrioritiseExecutionResult as y, type PrioritiseFallbackResult as z };