@fission-ai/openspec 1.4.1 → 1.5.0

package/dist/core/project-config.js

@@ -1,4 +1,4 @@
-import { existsSync, readFileSync } from 'fs';
+import { existsSync, readFileSync, statSync } from 'fs';
 import path from 'path';
 import { parse as parseYaml } from 'yaml';
 import { z } from 'zod';
@@ -34,8 +34,77 @@ export const ProjectConfigSchema = z.object({
     )
         .optional()
         .describe('Per-artifact rules, keyed by artifact ID'),
+    // Note: the `references` field (id strings or {id, remote} maps) is
+    // deliberately absent here — readProjectConfig parses and normalizes
+    // it by hand (see DeclarationEntry below); a schema entry nothing
+    // parses would only drift from the real behavior.
+    // Optional: the declared default store. Only consulted by root
+    // resolution when this openspec/ directory is config-only (no specs/
+    // or changes/); a fallback, never an override.
+    store: z
+        .string()
+        .optional()
+        .describe('Store id used as the OpenSpec root when no local planning shape exists'),
 });
-const MAX_CONTEXT_SIZE = 50 * 1024; // 50KB hard limit
+/**
+ * Parser for `references:` declarations: string entries or
+ * {id, remote} maps, normalized to DeclarationEntry[]. Dedup keys on
+ * id and keeps the first position; the first entry carrying a remote
+ * supplies it (a later duplicate fills a missing remote, never
+ * overrides). Invalid entries drop with a warning like other resilient
+ * fields; returns undefined when the field is absent or normalizes to
+ * empty.
+ */
+function parseDeclarationList(raw) {
+    const fieldName = 'references';
+    if (raw === undefined) {
+        return undefined;
+    }
+    if (!Array.isArray(raw)) {
+        console.warn(`Invalid '${fieldName}' field in config (must be an array of store ids)`);
+        return undefined;
+    }
+    const byId = new Map();
+    let droppedEntries = false;
+    let droppedRemotes = false;
+    for (const entry of raw) {
+        let declaration = null;
+        if (typeof entry === 'string') {
+            declaration = { id: entry };
+        }
+        else if (entry && typeof entry === 'object' && !Array.isArray(entry)) {
+            const candidate = entry;
+            if (typeof candidate.id === 'string') {
+                declaration = { id: candidate.id };
+                if (typeof candidate.remote === 'string' && candidate.remote.length > 0) {
+                    declaration.remote = candidate.remote;
+                }
+                else if (candidate.remote !== undefined) {
+                    droppedRemotes = true; // remote dropped, id kept
+                }
+            }
+        }
+        if (!declaration) {
+            droppedEntries = true;
+            continue;
+        }
+        const existing = byId.get(declaration.id);
+        if (!existing) {
+            byId.set(declaration.id, declaration);
+        }
+        else if (existing.remote === undefined && declaration.remote !== undefined) {
+            existing.remote = declaration.remote;
+        }
+    }
+    if (droppedEntries) {
+        console.warn(`Some '${fieldName}' entries are invalid, ignoring them`);
+    }
+    if (droppedRemotes) {
+        console.warn(`Some '${fieldName}' remotes are not non-empty strings; the ids are kept without a clone source`);
+    }
+    return byId.size > 0 ? [...byId.values()] : undefined;
+}
+export const MAX_CONTEXT_SIZE = 50 * 1024; // 50KB hard limit, shared with the references index
 /**
  * Read and parse openspec/config.yaml from project root.
  * Uses resilient parsing - validates each field independently using Zod safeParse.
@@ -56,13 +125,9 @@ const MAX_CONTEXT_SIZE = 50 * 1024; // 50KB hard limit
  * @returns Parsed config or null if file doesn't exist
  */
 export function readProjectConfig(projectRoot) {
-    // Try both .yaml and .yml, prefer .yaml
-    let configPath = path.join(projectRoot, 'openspec', 'config.yaml');
-    if (!existsSync(configPath)) {
-        configPath = path.join(projectRoot, 'openspec', 'config.yml');
-        if (!existsSync(configPath)) {
-            return null; // No config is OK
-        }
+    const configPath = resolveConfigFilePath(projectRoot);
+    if (configPath === null) {
+        return null; // No config is OK
     }
     try {
         const content = readFileSync(configPath, 'utf-8');
@@ -131,14 +196,32 @@ export function readProjectConfig(projectRoot) {
                 console.warn(`Invalid 'rules' field in config (must be object)`);
             }
         }
+        const references = parseDeclarationList(raw.references);
+        if (references) {
+            config.references = references;
+        }
+        // Parse store pointer field: a string, or dropped with a warning.
+        // (Root resolution does NOT use this parse — it uses readStorePointer
+        // below, which errors on malformed pointers instead of dropping.)
+        if (raw.store !== undefined) {
+            if (typeof raw.store === 'string') {
+                config.store = raw.store;
+            }
+            else {
+                console.warn(`Warning: ignoring invalid store: field in ${configPathForWarnings(projectRoot)} (must be a single store id string).`);
+            }
+        }
         // Return partial config even if some fields failed
         return Object.keys(config).length > 0 ? config : null;
     }
     catch (error) {
-        console.warn(`Failed to parse openspec/config.yaml:`, error);
+        console.warn(`Warning: could not parse ${configPathForWarnings(projectRoot)} (${error instanceof Error ? error.message.split('\n')[0] : String(error)}); ignoring it.`);
         return null;
     }
 }
+function configPathForWarnings(projectRoot) {
+    return resolveConfigFilePath(projectRoot) ?? path.join(projectRoot, 'openspec', 'config.yaml');
+}
 /**
  * Validate artifact IDs in rules against a schema's artifacts.
  * Called during instruction loading (when schema is known).
@@ -220,4 +303,71 @@ export function suggestSchemas(invalidSchemaName, availableSchemas) {
     message += `\nFix: Edit openspec/config.yaml and change 'schema: ${invalidSchemaName}' to a valid schema name`;
     return message;
 }
+/**
+ * Warning-silent targeted read of the `store:` pointer. Used by root
+ * resolution (which must not re-emit the resilient parser's field
+ * warnings) and by `openspec init`'s pointer guard. Unlike
+ * `readProjectConfig`, a malformed value is REPORTED, not dropped —
+ * a dropped pointer would silently flip where work lands.
+ */
+export function readStorePointer(projectRoot) {
+    const configPath = resolveConfigFilePath(projectRoot);
+    if (configPath === null) {
+        return { filePath: null };
+    }
+    try {
+        const raw = parseYaml(readFileSync(configPath, 'utf-8'));
+        // Empty, comments-only, or non-mapping configs carry no pointer;
+        // they are imperfect, not malformed (readProjectConfig owns the
+        // field warnings for those).
+        if (!raw || typeof raw !== 'object' || Array.isArray(raw)) {
+            return { filePath: configPath };
+        }
+        const value = raw.store;
+        if (value === undefined) {
+            return { filePath: configPath };
+        }
+        if (typeof value === 'string') {
+            return { value, filePath: configPath };
+        }
+        return { malformed: 'non_string', filePath: configPath };
+    }
+    catch {
+        return { malformed: 'unparseable', filePath: configPath };
+    }
+}
+/** Shared .yaml/.yml probe used by readProjectConfig and readStorePointer. */
+export function resolveConfigFilePath(projectRoot) {
+    const yamlPath = path.join(projectRoot, 'openspec', 'config.yaml');
+    if (existsSync(yamlPath)) {
+        return yamlPath;
+    }
+    const ymlPath = path.join(projectRoot, 'openspec', 'config.yml');
+    return existsSync(ymlPath) ? ymlPath : null;
+}
+/** Human rendering of a malformed pointer reason, shared by every surface. */
+export function storePointerProblem(reason) {
+    return reason === 'unparseable'
+        ? 'the config file could not be read as YAML'
+        : 'the store key must be a single store id string';
+}
+/**
+ * One classification for "real root vs config-only pointer dir", shared
+ * by root resolution and the init pointer guard so they can never
+ * disagree (slice 3.2).
+ */
+export function classifyOpenSpecDir(projectRoot) {
+    const openspecDir = path.join(projectRoot, 'openspec');
+    const hasPlanningShape = isDirectorySync(path.join(openspecDir, 'specs')) ||
+        isDirectorySync(path.join(openspecDir, 'changes'));
+    return { hasPlanningShape, pointer: readStorePointer(projectRoot) };
+}
+function isDirectorySync(candidatePath) {
+    try {
+        return statSync(candidatePath).isDirectory();
+    }
+    catch {
+        return false;
+    }
+}
 //# sourceMappingURL=project-config.js.map

package/dist/core/references.d.ts

@@ -0,0 +1,63 @@
+import { type StoreDiagnostic } from './store/errors.js';
+import { listStoreRegistryEntries } from './store/foundation.js';
+import { type ResolvedOpenSpecRoot } from './root-selection.js';
+import { type DeclarationEntry } from './project-config.js';
+export interface ReferenceSpecEntry {
+    id: string;
+    summary: string;
+}
+export interface ReferenceIndexEntry {
+    store_id: string;
+    root?: string;
+    specs?: ReferenceSpecEntry[];
+    fetch?: string;
+    status: StoreDiagnostic[];
+}
+/**
+ * Tolerant first-Purpose-line extraction. parseSpec() throws on specs
+ * without Purpose/Requirements sections; the index must never fail on an
+ * imperfect upstream spec, so this scans for the heading directly —
+ * fence-aware, so `## Purpose` inside a code block never matches, and
+ * tolerant of CommonMark closing hashes (`## Purpose ##`).
+ */
+export declare function extractFirstPurposeLine(markdown: string): string;
+export declare function fetchRecipe(storeId: string): string;
+/**
+ * Pure renderer for the artifact-instructions XML block. Also the byte
+ * budget's measuring stick (it is the larger rendering).
+ */
+export declare function renderReferencedStoresBlock(entries: ReferenceIndexEntry[]): string;
+/** Pure renderer for the apply-instructions markdown section. */
+export declare function renderReferencedStoresSection(entries: ReferenceIndexEntry[]): string;
+/**
+ * Strings rendered into agent guidance can come from cloned content
+ * (spec directory names, Purpose lines, config-declared remotes). One
+ * line in, one line out: control characters and newlines must never
+ * let hostile content forge instruction lines (slice 6.1 hardening).
+ */
+export declare function sanitizeInline(value: string, maxLength?: number): string;
+export interface AssembleReferenceIndexInput {
+    references: DeclarationEntry[];
+    resolvedRoot: ResolvedOpenSpecRoot;
+    globalDataDir?: string;
+    /**
+     * Health mode (3.6): false skips the spec-file reads AND the byte
+     * budget — entries carry no `specs`/`fetch` keys at all, and the
+     * content-only truncation diagnostic can never appear.
+     */
+    includeSpecs?: boolean;
+    /**
+     * Pre-read registry entries (3.6): `[]` = registry empty or absent,
+     * `null` = unreadable, undefined = read internally as before.
+     * (Mirrors the internal post-read variable — never inject a raw
+     * read result: a healthy-absent registry reads as null.)
+     */
+    registryEntries?: ReturnType<typeof listStoreRegistryEntries> | null;
+}
+/**
+ * Builds the referenced-store index. One registry read per call; one
+ * level deep (a referenced store's own references are never followed);
+ * self-references omitted; every failure degrades to a warning entry.
+ */
+export declare function assembleReferenceIndex(input: AssembleReferenceIndexInput): Promise<ReferenceIndexEntry[]>;
+//# sourceMappingURL=references.d.ts.map

package/dist/core/references.js

@@ -0,0 +1,310 @@
+/**
+ * Referenced-store index assembly (slice 3.1).
+ *
+ * A root's `openspec/config.yaml` may declare `references:` — store ids
+ * whose specs the root's work draws on. Instructions output carries an
+ * INDEX of those stores' specs (id, one-line summary, fetch recipe via
+ * `--store`), built live from the registered checkouts at assembly time.
+ * Content is never inlined; root resolution is never affected; problems
+ * degrade to `warning` diagnostics instead of failing generation.
+ */
+import * as fs from 'node:fs/promises';
+import * as os from 'node:os';
+import * as path from 'node:path';
+import { makeStoreDiagnostic } from './store/errors.js';
+import { isValidStoreId, listStoreRegistryEntries, readStoreRegistryState, } from './store/foundation.js';
+import { getStoreRootForBackend } from './store/registry.js';
+import { inspectRegisteredStore } from './root-selection.js';
+import { getSpecIds } from '../utils/item-discovery.js';
+import { FileSystemUtils } from '../utils/file-system.js';
+import { MAX_CONTEXT_SIZE } from './project-config.js';
+/**
+ * Shares the project-context cap: the rendered index is prompt material.
+ * Measured in UTF-8 bytes against the XML rendering (the larger of the
+ * two), entries and diagnostics included; only the truncation warning
+ * itself is exempt (no oscillation).
+ */
+const MAX_RENDERED_INDEX_SIZE = MAX_CONTEXT_SIZE;
+function warning(code, message, fix) {
+    return makeStoreDiagnostic('warning', code, message, { target: 'references', fix });
+}
+/**
+ * A remote is rendered into the pasteable clone command only when it is
+ * shell-inert: no whitespace, quotes, or metacharacters, and not
+ * flag-like (a config-supplied `--upload-pack=...` must never reach a
+ * command agents execute verbatim). Anything else falls back to the
+ * teammate-checkout wording.
+ */
+function isShellSafeRemote(remote) {
+    return /^[A-Za-z0-9@:/._~+-]+$/.test(remote) && !remote.startsWith('-');
+}
+function registerFix(id, remote) {
+    if (remote && isShellSafeRemote(remote)) {
+        // Verbatim-pasteable: absolute home path because tilde never
+        // expands outside a shell and agent JSON consumers execute argv.
+        // The checkout is quoted (homedirs may contain spaces); the remote
+        // is unquoted but gated by isShellSafeRemote above.
+        const checkout = path.join(os.homedir(), 'openspec', id);
+        // The fix renders on the machine that will paste it: POSIX shells
+        // get single quotes; cmd/PowerShell treat single quotes as literal
+        // characters, so win32 gets double quotes (valid everywhere).
+        const quoted = process.platform === 'win32' ? `"${checkout}"` : `'${checkout}'`;
+        return `git clone -- ${remote} ${quoted} && openspec store register ${quoted} --id ${id}`;
+    }
+    return `Get a checkout from a teammate and run: openspec store register <path> --id ${id}`;
+}
+/**
+ * Tolerant first-Purpose-line extraction. parseSpec() throws on specs
+ * without Purpose/Requirements sections; the index must never fail on an
+ * imperfect upstream spec, so this scans for the heading directly —
+ * fence-aware, so `## Purpose` inside a code block never matches, and
+ * tolerant of CommonMark closing hashes (`## Purpose ##`).
+ */
+export function extractFirstPurposeLine(markdown) {
+    const lines = markdown.split(/\r?\n/);
+    let inPurpose = false;
+    let fenceMarker = null;
+    for (const line of lines) {
+        // CommonMark: a fence closes only with its own marker kind.
+        const fence = line.match(/^\s*(```|~~~)/);
+        if (fence) {
+            if (fenceMarker === null) {
+                fenceMarker = fence[1];
+            }
+            else if (fence[1] === fenceMarker) {
+                fenceMarker = null;
+            }
+            continue;
+        }
+        if (fenceMarker !== null) {
+            continue;
+        }
+        const heading = line.match(/^(#{1,6})\s+(.*)$/);
+        if (heading) {
+            if (inPurpose) {
+                return '';
+            }
+            const title = heading[2].replace(/\s+#+\s*$/, '').trim();
+            inPurpose = title.toLowerCase() === 'purpose';
+            continue;
+        }
+        if (inPurpose && line.trim().length > 0) {
+            return line.trim();
+        }
+    }
+    return '';
+}
+async function collectSpecEntries(referencedRoot) {
+    const specIds = await getSpecIds(referencedRoot);
+    return Promise.all(specIds.map(async (specId) => {
+        let summary = '';
+        try {
+            const content = await fs.readFile(path.join(referencedRoot, 'openspec', 'specs', specId, 'spec.md'), 'utf-8');
+            summary = sanitizeInline(extractFirstPurposeLine(content));
+        }
+        catch {
+            // Unreadable spec file: index the id with an empty summary.
+        }
+        return { id: specId, summary };
+    }));
+}
+export function fetchRecipe(storeId) {
+    return `openspec show <spec-id> --type spec --store ${storeId}`;
+}
+function specLine(spec) {
+    // Ids are raw directory names from cloned content; summaries are
+    // sanitized at index time (collectSpecEntries).
+    const id = sanitizeInline(spec.id, 100);
+    return spec.summary ? `  - ${id}: ${spec.summary}` : `  - ${id}`;
+}
+/**
+ * Pure renderer for the artifact-instructions XML block. Also the byte
+ * budget's measuring stick (it is the larger rendering).
+ */
+export function renderReferencedStoresBlock(entries) {
+    const lines = [
+        '<referenced_stores>',
+        '<!-- Read-only upstream context. Fetch what you need; cite what you use. -->',
+    ];
+    for (const entry of entries) {
+        lines.push(...renderEntryLines(entry));
+    }
+    lines.push('</referenced_stores>');
+    return lines.join('\n');
+}
+/** Pure renderer for the apply-instructions markdown section. */
+export function renderReferencedStoresSection(entries) {
+    const lines = [
+        '### Referenced Stores',
+        '',
+        'Read-only upstream context. Fetch what you need; cite what you use.',
+        '',
+    ];
+    for (const entry of entries) {
+        lines.push(...renderEntryLines(entry));
+    }
+    return lines.join('\n');
+}
+/**
+ * Strings rendered into agent guidance can come from cloned content
+ * (spec directory names, Purpose lines, config-declared remotes). One
+ * line in, one line out: control characters and newlines must never
+ * let hostile content forge instruction lines (slice 6.1 hardening).
+ */
+export function sanitizeInline(value, maxLength = 300) {
+    // eslint-disable-next-line no-control-regex
+    const flattened = value.replace(/[\u0000-\u001f\u007f]+/g, ' ').trim();
+    return flattened.length > maxLength ? `${flattened.slice(0, maxLength)}…` : flattened;
+}
+function renderEntryLines(entry) {
+    const lines = [];
+    if (entry.root !== undefined) {
+        lines.push(`Store ${entry.store_id} (${entry.root}):`);
+        for (const spec of entry.specs ?? []) {
+            lines.push(specLine(spec));
+        }
+        if (entry.fetch) {
+            lines.push(`  Fetch: ${entry.fetch}`);
+        }
+        // Diagnostics on a resolved entry (e.g. truncation) render message
+        // AND fix — an orphan fix line would hide that the list is partial.
+        for (const diagnostic of entry.status) {
+            lines.push(`  Note: ${diagnostic.message}`);
+            if (diagnostic.fix) {
+                lines.push(`  Fix: ${diagnostic.fix}`);
+            }
+        }
+    }
+    else {
+        for (const diagnostic of entry.status) {
+            lines.push(`Store ${entry.store_id}: ${diagnostic.message}`);
+            if (diagnostic.fix) {
+                lines.push(`  Fix: ${diagnostic.fix}`);
+            }
+        }
+    }
+    return lines;
+}
+function renderedByteSize(entries) {
+    return Buffer.byteLength(renderReferencedStoresBlock(entries), 'utf-8');
+}
+/**
+ * Builds the referenced-store index. One registry read per call; one
+ * level deep (a referenced store's own references are never followed);
+ * self-references omitted; every failure degrades to a warning entry.
+ */
+export async function assembleReferenceIndex(input) {
+    const declarations = input.references;
+    if (declarations.length === 0) {
+        return [];
+    }
+    // null means the registry itself was unreadable (corrupt file).
+    let registryEntries;
+    if (input.registryEntries !== undefined) {
+        registryEntries = input.registryEntries;
+    }
+    else {
+        try {
+            const registry = await readStoreRegistryState(input.globalDataDir ? { globalDataDir: input.globalDataDir } : {});
+            registryEntries = registry ? listStoreRegistryEntries(registry) : [];
+        }
+        catch {
+            registryEntries = null;
+        }
+    }
+    const includeSpecs = input.includeSpecs !== false;
+    const resolvedRootPath = FileSystemUtils.canonicalizeExistingPath(input.resolvedRoot.path);
+    const entries = [];
+    for (const { id, remote } of declarations) {
+        // Registry-independent checks come first: an invalid id is an
+        // invalid id (and a self-reference is omittable) even when the
+        // registry is corrupt. The declared remote is only consulted after
+        // the id passes grammar.
+        if (!isValidStoreId(id)) {
+            entries.push({
+                store_id: id,
+                status: [
+                    warning('reference_invalid_id', `Reference '${id}' is not a valid store id.`, 'Use kebab-case store ids in the references list.'),
+                ],
+            });
+            continue;
+        }
+        if (input.resolvedRoot.storeId === id) {
+            continue; // Self-reference: meaningless, silently omitted.
+        }
+        if (registryEntries === null) {
+            entries.push({
+                store_id: id,
+                status: [
+                    warning('reference_registry_unreadable', `Referenced store '${id}' cannot be checked: the store registry is unreadable.`, 'Run: openspec store doctor'),
+                ],
+            });
+            continue;
+        }
+        const registryEntry = registryEntries.find((candidate) => candidate.id === id);
+        if (!registryEntry) {
+            entries.push({
+                store_id: id,
+                status: [
+                    warning('reference_unresolved', `Referenced store '${id}' is not registered on this machine.`, registerFix(id, remote)),
+                ],
+            });
+            continue;
+        }
+        let inspection;
+        try {
+            const storeRoot = getStoreRootForBackend(registryEntry.backend);
+            inspection = await inspectRegisteredStore(id, storeRoot);
+        }
+        catch (error) {
+            inspection = { kind: 'inspection_error', error };
+        }
+        if (inspection.kind !== 'ok') {
+            entries.push({
+                store_id: id,
+                status: [
+                    warning('reference_root_unhealthy', `Referenced store '${id}' is registered but not usable (${inspection.kind.replace(/_/g, ' ')}).`, `Run: openspec store doctor ${id}`),
+                ],
+            });
+            continue;
+        }
+        if (inspection.canonicalRoot === resolvedRootPath) {
+            continue; // Self-reference by path: silently omitted.
+        }
+        if (!includeSpecs) {
+            // Health mode: resolution facts only — no content, no budget.
+            entries.push({ store_id: id, root: inspection.canonicalRoot, status: [] });
+            continue;
+        }
+        const specs = await collectSpecEntries(inspection.canonicalRoot);
+        const entry = {
+            store_id: id,
+            root: inspection.canonicalRoot,
+            specs,
+            fetch: fetchRecipe(id),
+            status: [],
+        };
+        // Budget the real rendering: keep the longest spec-list prefix whose
+        // full rendered index stays under the cap. The truncation warning
+        // itself is exempt (added after the size decision — no oscillation).
+        entries.push(entry);
+        if (renderedByteSize(entries) > MAX_RENDERED_INDEX_SIZE) {
+            let low = 0;
+            let high = specs.length;
+            while (low < high) {
+                const mid = Math.ceil((low + high) / 2);
+                entry.specs = specs.slice(0, mid);
+                if (renderedByteSize(entries) > MAX_RENDERED_INDEX_SIZE) {
+                    high = mid - 1;
+                }
+                else {
+                    low = mid;
+                }
+            }
+            entry.specs = specs.slice(0, low);
+            entry.status.push(warning('reference_index_truncated', `Referenced store '${id}' index truncated at the 50KB budget (${low} of ${specs.length} specs listed).`, `List the rest directly: openspec list --specs --store ${id}`));
+        }
+    }
+    return entries;
+}
+//# sourceMappingURL=references.js.map

package/dist/core/relationship-health.d.ts

@@ -0,0 +1,65 @@
+/**
+ * Relationship health composition (slice 3.6).
+ *
+ * One read-only answer to "are the roots this work relates to available
+ * on this machine?" — pure composition over inputs the doctor command
+ * gathers. The lock's four categories stay separated: root health,
+ * store metadata health, and reference health. Nothing here (or
+ * downstream) clones, syncs, or repairs.
+ */
+import { type StoreDiagnostic } from './store/errors.js';
+import { type ReferenceIndexEntry } from './references.js';
+import { type ResolvedOpenSpecRoot } from './root-selection.js';
+export interface RelationshipHealth {
+    root: {
+        path: string;
+        source: ResolvedOpenSpecRoot['source'];
+        store_id?: string;
+        healthy: boolean;
+        status: StoreDiagnostic[];
+    };
+    store: {
+        id: string;
+        metadata: {
+            present: boolean;
+            valid: boolean;
+            remote?: string;
+        };
+        origin_url?: string;
+        status: StoreDiagnostic[];
+    } | null;
+    references: ReferenceIndexEntry[];
+    status: StoreDiagnostic[];
+}
+export interface InspectRelationshipsInput {
+    root: ResolvedOpenSpecRoot;
+    rootHealthy: boolean;
+    rootStatus?: StoreDiagnostic[];
+    /** Store facts for store-backed roots (explicit or declared). */
+    storeFacts?: {
+        id: string;
+        metadataPresent: boolean;
+        metadataValid: boolean;
+        canonicalRemote?: string;
+        originUrl?: string;
+    };
+    referenceEntries: ReferenceIndexEntry[];
+    registryUnreadable: boolean;
+    /** A real root whose config also declares a store: pointer (3.2). */
+    bothShapesPointer?: {
+        value: string;
+        filePath: string;
+    };
+    /** A real root whose store: pointer value is malformed (3.2). */
+    malformedPointer?: {
+        filePath: string;
+        reason: 'unparseable' | 'non_string';
+    };
+    /** Reference declarations in a pointer directory's own config are inert. */
+    inertPointerDeclarations?: {
+        filePath: string;
+        fields: string[];
+    };
+}
+export declare function inspectRelationships(input: InspectRelationshipsInput): RelationshipHealth;
+//# sourceMappingURL=relationship-health.d.ts.map