@unified-product-graph/sdk 0.6.0

package/dist/index.d.ts

@@ -0,0 +1,678 @@
+import { U as UPGFileStore, I as IntegrityReport, a as UPGPortfolioStore } from './logic-DriXyFKi.js';
+export { A as AdjacentEdge, b as AlternateAnchor, c as AnchorHint, B as BUSINESS_AREA_META, d as BusinessArea, C as ChangeEntry, e as CrossEdgeMigrationResult, D as DESCRIPTION_SOFT_LIMIT, f as DanglingEdgeClass, g as DanglingEdgeRecord, h as DanglingEdgeReport, E as ENTITY_CLASSIFICATION, i as EdgeAlias, j as EdgeInferenceFail, k as EdgeInferenceOk, l as EdgeInferenceResult, m as EdgeInferenceSuggestion, n as EdgePairValidationFail, o as EdgePairValidationOk, p as EdgePairValidationResult, q as EvalResult, r as InferEdgeTypeError, s as InspectResult, t as InspectViolation, L as LengthCheckResult, M as MergeResult, u as MissingEntityRow, P as PROPERTY_TREE_SOFT_BYTES, v as PROPERTY_TREE_SOFT_DEPTH, w as PlanResult, x as PortfolioLoadResult, y as PrioritiseExecutionResult, z as PrioritiseFallbackResult, F as PrioritiseRankedRow, G as PropertyTypeCheckResult, H as PropertyTypeViolation, Q as QuarantinedEntity, R as ReflectPrompt, J as ReflectPromptKind, K as ReflectResult, S as SchemaDriftSummary, T as TIER_CLUSTER_META, N as TIER_DESCRIPTIONS, O as TITLE_SOFT_LIMIT, V as Tier, W as TierCluster, X as TraceResult, Y as TraceTrailRow, Z as ValidateGraphBody, _ as buildAdjacentEdges, $ as buildAlternateAnchors, a0 as buildAnchorHint, a1 as buildResolverHints, a2 as checkLengthCaps, a3 as checkPropertyTypes, a4 as classifyDanglingEdges, a5 as collectAntiPatternInputs, a6 as computeSchemaDriftSummary, a7 as edgeId, a8 as evaluateExpression, a9 as executeInspect, aa as executePlan, ab as executePrioritise, ac as executeReflect, ad as executeTrace, ae as getClassification, af as getEntitiesForBusinessArea, ag as getEntitiesForCluster, ah as getEntitiesForTier, ai as getEntitiesForTierAndArea, aj as getEntitiesUpToTier, ak as getTierEntityCount, al as getTierForStage, am as inferEdgeType, an as inferEdgeTypeWithTier, ao as isRelevantForStage, ap as nodeId, aq as productId, ar as renderDanglingReport, as as renderDriftSummary, at as renderPropertyTypeWarning, au as validateClassificationCoverage, av as validateEdgeTypePair } from './logic-DriXyFKi.js';
+import { UPGEdge, UPGProductStage, UPGBaseNode, UPGEdgeType, UPGPortfolio, UPGProductArea, UPGOrganization, UPGPortfolioDocument } from '@unified-product-graph/core';
+export { EntityTypeResolution, UPGCrossEdge, UPGPortfolioDocument, UPG_ANTI_PATTERNS, UPG_REGIONS, UnknownEntityTypeError, resolveEntityType } from '@unified-product-graph/core';
+
+/**
+ * Shared tool logic. Pure functions that operate on a UPGFileStore.
+ *
+ * Used by both the MCP server (server.ts) and the CLI (@unified-product-graph/mcp).
+ * Extract here, import everywhere.
+ */
+
+/**
+ * Validate a status value against the lifecycle phases for an entity type.
+ * Returns a warning string if the status is invalid, or undefined if valid / no lifecycle.
+ */
+declare function validateStatusAgainstLifecycle(entityType: string, status: string): string | undefined;
+/**
+ * Returns the initial_phase for an entity type, or undefined if the type has no lifecycle.
+ */
+declare function getDefaultStatus(entityType: string): string | undefined;
+/**
+ * Backfill `slug` on a freshly-built node before it's added to the store.
+ * Picks the auto-generated slug from `title`, resolved against
+ * every existing slug + alias of the same `type` in the same product.
+ *
+ * No-op if the node already carries an explicit slug.
+ */
+declare function autoFillSlug(node: UPGBaseNode, store: UPGFileStore): void;
+declare function normalizeTags(tags: unknown): string[] | undefined;
+declare const BUSINESS_AREAS: Record<string, {
+    emoji: string;
+    types: string[];
+}>;
+declare const STAGE_COVERAGE_TARGETS: Record<UPGProductStage, string[]>;
+/**
+ * Resolve the canonical UPGProductStage for digest coverage. Returns
+ * `'concept'` as the default when stage is missing or unrecognised — concept
+ * is the narrowest expectation surface, so we under-grade rather than
+ * over-grade. Legacy `"idea"` and friends route through `coerceProductStage`
+ * (which lives in `@unified-product-graph/core`); the inline `"idea" →
+ * "concept"` fallback below is defensive in case the core helper is ever
+ * unavailable.
+ */
+declare function resolveCoverageStage(rawStage: unknown): UPGProductStage;
+declare const LIFECYCLE_PHASES: Record<string, string[]>;
+declare const CHAINS: readonly [{
+    readonly name: "persona → job";
+    readonly from: "persona";
+    readonly to: "job";
+    readonly edgePattern: "job";
+}, {
+    readonly name: "job → need";
+    readonly from: "job";
+    readonly to: "need";
+    readonly edgePattern: "need";
+}, {
+    readonly name: "opportunity → solution";
+    readonly from: "opportunity";
+    readonly to: "solution";
+    readonly edgePattern: "solution";
+}, {
+    readonly name: "solution → hypothesis";
+    readonly from: "solution";
+    readonly to: "hypothesis";
+    readonly edgePattern: "hypothesis";
+}, {
+    readonly name: "hypothesis → experiment_plan";
+    readonly from: "hypothesis";
+    readonly to: "experiment_plan";
+    readonly edgePattern: "experiment_plan";
+}, {
+    readonly name: "experiment_run → learning";
+    readonly from: "experiment_run";
+    readonly to: "learning";
+    readonly edgePattern: "learning";
+}, {
+    readonly name: "objective → key_result";
+    readonly from: "objective";
+    readonly to: "key_result";
+    readonly edgePattern: "key_result";
+}, {
+    readonly name: "feature → story_statement";
+    readonly from: "feature";
+    readonly to: "story_statement";
+    readonly edgePattern: "story_statement";
+}];
+/** Get sort priority for a type (lower = higher in tree). Unknown types sort last. */
+declare function typeSortPriority(type: string): number;
+/** Sort nodes by type priority, then alphabetically by title within same type */
+declare function sortByType(nodes: UPGBaseNode[]): UPGBaseNode[];
+interface CoverageRegion {
+    covered: number;
+    total: number;
+    /**
+     * NEW (Finding 9 / UPG-512): True when this region is on the product
+     * stage's expected-coverage list. Regions where this is `false` are
+     * surfaced for awareness but excluded from `stage_summary.overall_pct`.
+     */
+    counted_toward_stage: boolean;
+    types_present: string[];
+    types_missing: string[];
+}
+interface CoverageStageSummary {
+    stage: UPGProductStage;
+    /** Number of regions counted toward this stage's completeness. */
+    regions_counted: number;
+    /** Counted regions that are fully covered (covered === total). */
+    regions_complete: number;
+    /** Counted regions with partial coverage (0 < covered < total). */
+    regions_partial: number;
+    /** Whole-number percentage 0-100, averaged across counted regions only. */
+    overall_pct: number;
+}
+interface GraphDigest {
+    product: {
+        title: string;
+        stage: string;
+    };
+    counts: {
+        total_nodes: number;
+        total_edges: number;
+        by_type: Record<string, number>;
+    };
+    health: {
+        orphan_count: number;
+        orphan_rate: number;
+        connectivity: number;
+        validation_rate: number;
+        user_coverage: number;
+    };
+    chains: Record<string, number>;
+    /**
+     * Per-region coverage map. Keys are `BUSINESS_AREAS` ids (e.g.
+     * `identity`, `understanding`). The new stage-aware aggregate is at
+     * `coverage.stage_summary` (typed loosely here so `Record<string,
+     * CoverageRegion>` index lookups stay correct for callers).
+     *
+     * NOTE: callers iterating `Object.entries(coverage)` should skip the
+     * `stage_summary` key — it carries a different shape.
+     */
+    coverage: Record<string, CoverageRegion> & {
+        stage_summary?: CoverageStageSummary;
+    };
+    lifecycle: Record<string, number>;
+}
+declare function computeGraphDigest(store: UPGFileStore): GraphDigest;
+interface SearchResult {
+    node: UPGBaseNode;
+    score: number;
+    match_field: string;
+}
+declare function searchNodes(store: UPGFileStore, query: string, options?: {
+    type?: string;
+    fields?: string[];
+    limit?: number;
+}): SearchResult[];
+declare function computeHealthScore(digest: GraphDigest): number;
+declare function getOrphans(store: UPGFileStore): UPGBaseNode[];
+interface ListNodesOptions {
+    type?: string;
+    status?: string;
+    parentId?: string;
+    tags?: string[];
+    includeEdges?: boolean;
+    countOnly?: boolean;
+    limit?: number;
+    offset?: number;
+}
+interface ListNodesResult {
+    nodes: Array<Record<string, unknown>>;
+    total: number;
+}
+declare function listNodes(store: UPGFileStore, options?: ListNodesOptions): ListNodesResult;
+interface GetNodeResult {
+    node: UPGBaseNode;
+    edges_out: Array<Record<string, unknown>>;
+    edges_in: Array<Record<string, unknown>>;
+}
+declare function getNode(store: UPGFileStore, args: {
+    node_id: string;
+    compact_edges?: boolean;
+}): GetNodeResult | null;
+interface GetNodesResult {
+    nodes: Array<GetNodeResult>;
+    total: number;
+    not_found?: string[];
+}
+declare function getNodes(store: UPGFileStore, args: {
+    ids: string[];
+    compact_edges?: boolean;
+}): GetNodesResult;
+interface CreateNodeArgs {
+    type: string;
+    title: string;
+    description?: string;
+    tags?: unknown;
+    status?: string;
+    properties?: Record<string, unknown>;
+    parent_id?: string;
+}
+interface CreateNodeResult {
+    node: UPGBaseNode;
+    edge: UPGEdge | null;
+    warning?: string;
+}
+declare function createNode(store: UPGFileStore, args: CreateNodeArgs): CreateNodeResult;
+interface CreateEdgeArgs {
+    source_id: string;
+    target_id?: string;
+    target_title?: string;
+    target_type?: string;
+    type?: string;
+}
+type CreateEdgeResult = {
+    edge: UPGEdge;
+    warning?: string;
+} | {
+    error: string;
+    /**
+     * Source/target types when the failure is a "no canonical edge"
+     * resolver miss — surfaced so the MCP handler can attach
+     * `anchor_hint` / `alternate_anchors` / `adjacent_edges` enrichment
+     * blocks (UPG-505 + UPG-515).
+     */
+    no_canonical_edge_for?: {
+        source_type: string;
+        target_type: string;
+    };
+};
+declare function createEdge(store: UPGFileStore, args: CreateEdgeArgs): CreateEdgeResult;
+interface DeleteNodeResult {
+    deleted_node_id: string;
+    deleted_node_title: string;
+    deleted_edge_ids: string[];
+}
+declare function deleteNode(store: UPGFileStore, args: {
+    node_id: string;
+}): DeleteNodeResult;
+interface DeleteEdgeResult {
+    deleted_edge_id: string;
+}
+declare function deleteEdge(store: UPGFileStore, args: {
+    edge_id: string;
+}): DeleteEdgeResult;
+interface MoveNodeArgs {
+    node_id: string;
+    new_parent_id: string;
+    /** Override the inferred edge type. Must be a key in UPG_EDGE_CATALOG. */
+    new_edge_type?: string;
+    /**
+     * Disambiguate when the node has more than one hierarchy edge. Caller
+     * specifies which existing parent edge to delete; otherwise the move is
+     * rejected with the candidate edge ids.
+     */
+    old_edge_id?: string;
+}
+type MoveNodeResult = {
+    moved: true;
+    node_id: string;
+    new_edge: UPGEdge;
+    removed_edge_id: string | null;
+    /** Removed edge object — exposed for caller-driven rollback (e.g. batch). */
+    removed_edge?: UPGEdge;
+    warning?: string;
+} | {
+    moved: false;
+    error: string;
+};
+declare function moveNode(store: UPGFileStore, args: MoveNodeArgs): MoveNodeResult;
+interface BatchMoveNodesResult {
+    moves: Array<{
+        node_id: string;
+        new_edge: UPGEdge;
+        removed_edge_id: string | null;
+    }>;
+    count: number;
+    warnings?: string[];
+}
+type BatchMoveNodesOutcome = {
+    ok: true;
+    result: BatchMoveNodesResult;
+} | {
+    ok: false;
+    error: string;
+    failed_at_index: number | null;
+};
+/**
+ * Apply a batch of moves atomically. Validates every move against the catalog
+ * BEFORE any mutation; on the first failure the batch is rejected with no
+ * changes to the graph. If a mutation fails mid-application (highly unusual
+ * given upfront validation), already-applied moves are rolled back.
+ */
+declare function batchMoveNodes(store: UPGFileStore, moves: MoveNodeArgs[]): BatchMoveNodesOutcome;
+interface BatchNodeInput {
+    type: string;
+    title: string;
+    description?: string;
+    status?: string;
+    tags?: unknown;
+    properties?: Record<string, unknown>;
+    parent_id?: string;
+    parent_ref?: string;
+}
+interface BatchEdgeInput {
+    from_ref: string;
+    to_ref: string;
+    type?: string;
+}
+interface BatchCreateArgs {
+    nodes: BatchNodeInput[];
+    edges?: BatchEdgeInput[];
+}
+interface BatchCreateOk {
+    ok: true;
+    created: Array<{
+        id: string;
+        type: string;
+        title: string;
+        status?: string;
+    }>;
+    edges: UPGEdge[];
+    explicit_edges?: UPGEdge[];
+    count: number;
+    warnings?: string[];
+}
+interface BatchCreateFail {
+    ok: false;
+    error: string;
+}
+type BatchCreateResult = BatchCreateOk | BatchCreateFail;
+/**
+ * Atomic batch creation — nodes plus optional explicit edges in a single
+ * all-or-nothing transaction.
+ *
+ * Validation pass walks every node and every edge against the canonical
+ * schema BEFORE any mutation. If anything fails, no nodes and no edges land.
+ *
+ * Apply pass creates nodes (with parent_ref / parent_id auto-edges from
+ * inference; failed inference = warning, never fabrication),
+ * then creates the explicit edges. If ANY apply step throws, rolls back
+ * every already-applied node + edge so the graph is bit-for-bit identical
+ * to the pre-call state.
+ */
+declare function batchCreateNodes(store: UPGFileStore, args: BatchCreateArgs): BatchCreateResult;
+interface MigrateNodeTypeArgs {
+    node_id: string;
+    new_type: string;
+}
+type MigrateNodeTypeResult = {
+    migrated: true;
+    node_id: string;
+    from_type: string;
+    to_type: string;
+    edges_rewritten: Array<{
+        id: string;
+        from: string;
+        to: string;
+    }>;
+    warning?: string;
+} | {
+    migrated: false;
+    error: string;
+    suggestions?: string[];
+};
+/**
+ * Atomically change a single node's entity type and rewrite every incident
+ * edge to its new canonical edge type derived from the catalog.
+ *
+ * Distinct from `migrate_type` (which rewrites EVERY node of a given type
+ * across the whole graph by string substitution). This single-node variant
+ * re-infers each affected edge from (source.type, target.type) via
+ * `inferEdgeTypeWithTier`, so it preserves correctness when the graph mixes
+ * canonical and deprecated types.
+ *
+ * If any incident edge cannot be re-inferred, the entire migration is
+ * rejected and the graph is left unchanged. Rollback restores both the
+ * node's original type and any edges already rewritten.
+ */
+declare function migrateNodeType(store: UPGFileStore, args: MigrateNodeTypeArgs): MigrateNodeTypeResult;
+
+interface UPGClientOptions {
+    /** Path to the .upg file on disk. */
+    file: string;
+    /**
+     * Skip auto-load on first operation (default: false).
+     * When true, call `await client.load()` manually before any operation.
+     */
+    lazy?: boolean;
+}
+interface NodeListOptions extends ListNodesOptions {
+}
+interface EdgeListOptions {
+    source?: string;
+    target?: string;
+    type?: UPGEdgeType;
+}
+interface HealthResult {
+    score: number;
+    digest: GraphDigest;
+}
+interface SearchOptions {
+    /** Maximum number of results (default: 20). */
+    limit?: number;
+    /** Restrict to a single entity type. */
+    type?: string;
+}
+declare class UPGClient {
+    private readonly options;
+    private store;
+    private loadPromise;
+    /** Node operations namespace. */
+    readonly nodes: NodesAPI;
+    /** Edge operations namespace. */
+    readonly edges: EdgesAPI;
+    constructor(options: UPGClientOptions);
+    /**
+     * Load the .upg file. Called automatically on first operation unless
+     * `{ lazy: true }` was set. Safe to call multiple times — repeated calls
+     * are coalesced. If load fails (transient I/O, parse error, etc.) the
+     * promise is rejected AND the cached promise is cleared, so the next
+     * call retries from scratch rather than re-throwing the stale error.
+     */
+    load(): Promise<void>;
+    /** Internal: get the loaded store, loading on demand. */
+    getStore(): Promise<UPGFileStore>;
+    /** Persist pending changes to disk. Called automatically after mutations. */
+    flush(): Promise<void>;
+    /** Compute a health score (0–100) plus the underlying graph digest. */
+    health(): Promise<HealthResult>;
+    /** Search nodes by free-text query. */
+    search(query: string, options?: SearchOptions): Promise<SearchResult[]>;
+    /**
+     * Verify integrity of the loaded graph. Returns the integrity report from
+     * the last load + any in-memory mutation checks. `null` indicates no
+     * integrity issues were detected.
+     */
+    verify(): Promise<IntegrityReport | null>;
+    /**
+     * Diff against a previous version. Not yet implemented — tracked in
+     * UPG-541 follow-up. Will return a structured changeset between the
+     * current graph and the named ref (git revision or snapshot id).
+     */
+    diff(_ref: string): Promise<never>;
+    /** Release file watchers and free resources. */
+    close(): Promise<void>;
+}
+declare class NodesAPI {
+    private readonly client;
+    constructor(client: UPGClient);
+    /**
+     * Create a node. The `type` is validated against the UPG entity catalog —
+     * deprecated aliases are accepted with a warning, genuinely unknown types
+     * throw `UnknownEntityTypeError`.
+     */
+    create(args: CreateNodeArgs): Promise<CreateNodeResult>;
+    /** List nodes, optionally filtered by type / status / tag. */
+    list(options?: NodeListOptions): Promise<ListNodesResult>;
+    /** Get a single node by id. Returns `undefined` if not found. */
+    get(id: string): Promise<UPGBaseNode | undefined>;
+    /** Update a node by id. Returns the updated node. */
+    update(id: string, patch: Partial<UPGBaseNode>): Promise<UPGBaseNode>;
+    /** Delete a node and all incident edges. */
+    delete(id: string): Promise<DeleteNodeResult>;
+}
+declare class EdgesAPI {
+    private readonly client;
+    constructor(client: UPGClient);
+    /**
+     * Connect two nodes with an edge. Edge type is inferred from source +
+     * target entity types if not provided.
+     */
+    connect(sourceId: string, targetId: string, opts?: Partial<CreateEdgeArgs>): Promise<CreateEdgeResult>;
+    /** List edges, optionally filtered by source / target / type. */
+    list(options?: EdgeListOptions): Promise<UPGEdge[]>;
+    /** Delete an edge by id. */
+    delete(id: string): Promise<DeleteEdgeResult>;
+}
+
+/**
+ * Workspace bootstrap. Holds the core logic for `init_workspace`.
+ *
+ * Extracted from server.ts so the bug-prone fs choreography can be unit-tested
+ * against real tmp directories without booting the MCP transport.
+ *
+ * Two bugs this module guards against:
+ * 1. `readdir` returning the `.upg` workspace directory itself as an entry
+ *    that "ends with .upg". The old code tried to rename `.upg → .upg/.upg`
+ *    and crashed with EINVAL.
+ * 2. A user who already organised their `.upg` files inside `.upg/` re-running
+ *    `init_workspace` from the project root. The old code found nothing at
+ *    root and registered an empty product list. The new code discovers
+ *    pre-existing siblings and registers them non-destructively.
+ */
+
+interface WorkspaceProduct {
+    file: string;
+    title: string;
+}
+interface InitWorkspaceArgs {
+    cwd: string;
+    store: UPGFileStore;
+    moveExisting?: boolean;
+}
+interface InitWorkspaceResult {
+    workspace_path: string;
+    default_product: string;
+    products: WorkspaceProduct[];
+    current_product: {
+        title: string;
+        entities: number;
+    };
+}
+declare class WorkspaceAlreadyExistsError extends Error {
+    constructor();
+}
+declare class WorkspaceNotInitialisedError extends Error {
+    constructor();
+}
+declare class InvalidProductNameError extends Error {
+    constructor(reason: string);
+}
+/**
+ * Thrown when a `create_product` / product-stage write attempts to
+ * persist a non-canonical UPGProductStage value. Surfaces the canonical set
+ * + any documented coercion target in the error message so the caller can
+ * fix the input.
+ */
+declare class InvalidProductStageError extends Error {
+    constructor(message: string);
+}
+declare function initWorkspace({ cwd, store, moveExisting, }: InitWorkspaceArgs): Promise<InitWorkspaceResult>;
+interface CreateProductArgs {
+    cwd: string;
+    store: UPGFileStore;
+    name: string;
+    slug?: string;
+    description?: string;
+    stage?: UPGProductStage;
+    /**
+     * Optional portfolio node id in the CURRENT loaded store. When provided,
+     * a `product` node + `portfolio_contains_product` edge are created in the
+     * current store to express the hierarchy (portfolios live in a single .upg).
+     */
+    portfolio_id?: string;
+}
+interface CreateProductResult {
+    id: string;
+    file: string;
+    slug: string;
+    title: string;
+    workspace_path: string;
+    portfolio_attached: boolean;
+}
+declare function createProduct(args: CreateProductArgs): Promise<CreateProductResult>;
+
+/**
+ * Portfolio routing helpers — UPG-526.
+ *
+ * Portfolio-scoped entity types (`portfolio`, `organization`, `product_area`)
+ * belong in `.upg/portfolio.upg` rather than the active product's `nodes[]`.
+ * These helpers centralise:
+ *   - resolving the portfolio path for the current workspace
+ *   - loading-or-initialising the portfolio store
+ *   - appending entities to the right portfolio array (or setting the
+ *     singleton `organization`)
+ *   - reading portfolio-scoped entities back out in a shape compatible with
+ *     `list_portfolios` / `list_product_areas`
+ *
+ * The set of portfolio-scoped types is intentionally narrow and documented as
+ * `PORTFOLIO_SCOPED_TYPES`. Adding a new type means:
+ *   1. extending `UPGPortfolioDocument` in `@unified-product-graph/core`
+ *   2. extending this set
+ *   3. extending the write-routing switch in `writePortfolioScopedNode`
+ */
+
+/** Entity types that live in `.upg/portfolio.upg` instead of a product graph. */
+declare const PORTFOLIO_SCOPED_TYPES: ReadonlySet<string>;
+/** Default portfolio filename within a `.upg/` workspace. */
+declare const PORTFOLIO_FILENAME = "portfolio.upg";
+/** True when the entity type belongs in the portfolio document. */
+declare function isPortfolioScopedType(type: string): boolean;
+/**
+ * Resolve the portfolio file path for the current workspace.
+ * Returns null if the cwd has no `.upg/` directory.
+ */
+declare function resolvePortfolioPath(cwd: string): string | null;
+/**
+ * Resolve the portfolio file path, creating the `.upg/` directory if it does
+ * not exist. Used by write paths that need to mint a portfolio document on
+ * demand (e.g. first portfolio entity in a workspace that has product files but
+ * never had a portfolio doc).
+ */
+declare function resolveOrCreatePortfolioPath(cwd: string): string;
+/**
+ * Open (or initialise) the portfolio store at the given path. Caller is
+ * responsible for `flush()`-ing the store when the mutation is committed.
+ */
+declare function openPortfolioStore(portfolioPath: string): Promise<UPGPortfolioStore>;
+interface WritePortfolioNodeArgs {
+    /** Entity type — must satisfy `isPortfolioScopedType`. */
+    type: string;
+    /** Title for the new entity (or the organisation). */
+    title: string;
+    description?: string;
+    /** Free-form properties; subset is hoisted onto the typed shape per type. */
+    properties?: Record<string, unknown>;
+    /** When type === 'organization', allow overwriting an existing org. */
+    overwrite_organization?: boolean;
+}
+interface WritePortfolioNodeResult {
+    /** Persisted entity shape (the typed record actually written). */
+    entity: UPGPortfolio | UPGProductArea | UPGOrganization;
+    /** Where in the portfolio document the entity was written. */
+    written_to: 'portfolios' | 'product_areas' | 'organization';
+    /** Absolute portfolio file path. */
+    portfolio_file: string;
+    /** Optional warning (e.g. organization overwrite happened). */
+    warning?: string;
+}
+declare class PortfolioRoutingError extends Error {
+    constructor(message: string);
+}
+/**
+ * Append (or set, for `organization`) a portfolio-scoped entity into the
+ * portfolio document. Creates `.upg/portfolio.upg` on demand.
+ *
+ * For `organization`: refuses to overwrite an existing org unless
+ * `overwrite_organization: true` is supplied. The auto-generated org from
+ * `loadOrInit` is treated as a placeholder (org id starting with `org_` and
+ * title "Portfolio") and may be replaced silently.
+ */
+declare function writePortfolioScopedNode(cwd: string, args: WritePortfolioNodeArgs): Promise<WritePortfolioNodeResult>;
+/**
+ * Open the portfolio store if one exists. Returns null when there is no
+ * workspace and no portfolio document on disk — callers use this to render an
+ * empty list instead of erroring.
+ */
+declare function openPortfolioStoreIfExists(cwd: string): Promise<UPGPortfolioStore | null>;
+/**
+ * A lightweight product reference recorded on the portfolio document. The full
+ * UPG spec (`UPGPortfolioDocument.products`) types this slot as
+ * `UPGProduct & { nodes; edges }`, but the MCP model keeps each product in its
+ * own `.upg` file. The reference shape below carries just enough to look the
+ * product up later (id + file_path) plus a denormalised title for human-
+ * readable listings.
+ *
+ * If/when the spec adds an explicit `UPGProductReference` type, this shape
+ * should migrate to it. The fields are intentionally additive — every field
+ * other than `id` is optional so the record stays forward-compatible.
+ */
+interface PortfolioProductReference {
+    id: string;
+    /** Workspace-relative path to the product's `.upg` file, when known. */
+    file_path?: string;
+    /** Display title; denormalised from the product's own `product.title`. */
+    title?: string;
+}
+/**
+ * Ensure that a product is registered on `portfolio.upg.products[]`. No-op when
+ * an entry with the same `id` already exists. Does NOT flush — caller flushes
+ * once after registering both source and target products in a single pass.
+ *
+ * @returns true when a new entry was appended, false when already present.
+ */
+declare function registerProductOnPortfolio(doc: UPGPortfolioDocument, ref: PortfolioProductReference): boolean;
+/**
+ * Best-effort lookup of a product's `.upg` file and title given its product
+ * id. Walks the workspace `.upg/` directory looking for a file whose
+ * `product.id` matches. Returns null when not found or when the workspace
+ * lookup fails.
+ */
+declare function findProductFileById(cwd: string, productId: string): {
+    file_path: string;
+    title: string;
+} | null;
+
+export { BUSINESS_AREAS, type BatchCreateArgs, type BatchCreateFail, type BatchCreateOk, type BatchCreateResult, type BatchEdgeInput, type BatchMoveNodesOutcome, type BatchMoveNodesResult, type BatchNodeInput, CHAINS, type CoverageRegion, type CoverageStageSummary, type CreateEdgeArgs, type CreateEdgeResult, type CreateNodeArgs, type CreateNodeResult, type CreateProductArgs, type CreateProductResult, type DeleteEdgeResult, type DeleteNodeResult, type EdgeListOptions, type GetNodeResult, type GetNodesResult, type GraphDigest, type HealthResult, type InitWorkspaceArgs, type InitWorkspaceResult, IntegrityReport, InvalidProductNameError, InvalidProductStageError, LIFECYCLE_PHASES, type ListNodesOptions, type ListNodesResult, type MigrateNodeTypeArgs, type MigrateNodeTypeResult, type MoveNodeArgs, type MoveNodeResult, type NodeListOptions, PORTFOLIO_FILENAME, PORTFOLIO_SCOPED_TYPES, type PortfolioProductReference, PortfolioRoutingError, STAGE_COVERAGE_TARGETS, type SearchOptions, type SearchResult, UPGClient, type UPGClientOptions, UPGFileStore, UPGPortfolioStore, WorkspaceAlreadyExistsError, WorkspaceNotInitialisedError, type WorkspaceProduct, type WritePortfolioNodeArgs, type WritePortfolioNodeResult, autoFillSlug, batchCreateNodes, batchMoveNodes, computeGraphDigest, computeHealthScore, createEdge, createNode, createProduct, deleteEdge, deleteNode, findProductFileById, getDefaultStatus, getNode, getNodes, getOrphans, initWorkspace, isPortfolioScopedType, listNodes, migrateNodeType, moveNode, normalizeTags, openPortfolioStore, openPortfolioStoreIfExists, registerProductOnPortfolio, resolveCoverageStage, resolveOrCreatePortfolioPath, resolvePortfolioPath, searchNodes, sortByType, typeSortPriority, validateStatusAgainstLifecycle, writePortfolioScopedNode };