@nazty_labs/common-ground 0.5.1

package/dist/store.d.ts

@@ -0,0 +1,452 @@
+import { type RegistryRecord, type ChapterRecord, type Definition, type UpdateRequest } from './model.js';
+export declare const same: (a: unknown, b: unknown) => boolean;
+export declare class Store {
+    root: string;
+    constructor(root: string);
+    file(name: string): string;
+    safe(relative: string, allowMissing?: boolean): Promise<string>;
+    chapters(registry: RegistryRecord): {
+        key: string;
+        pillar: {
+            id: string;
+            title: string;
+            scope: string;
+            excludes: string;
+            chapters: {
+                id: string;
+                title: string;
+                scope: string;
+                excludes: string;
+                paths: string[];
+                revision: number;
+                facts: {
+                    id: string;
+                    statement: string;
+                    evidence: {
+                        path: string;
+                        quote: string;
+                    }[];
+                    sourceScope: string[];
+                    dependsOn: string[];
+                }[];
+                sources: Record<string, string>;
+                dependencyFingerprints: Record<string, string>;
+            }[];
+        };
+        chapter: {
+            id: string;
+            title: string;
+            scope: string;
+            excludes: string;
+            paths: string[];
+            revision: number;
+            facts: {
+                id: string;
+                statement: string;
+                evidence: {
+                    path: string;
+                    quote: string;
+                }[];
+                sourceScope: string[];
+                dependsOn: string[];
+            }[];
+            sources: Record<string, string>;
+            dependencyFingerprints: Record<string, string>;
+        };
+    }[];
+    chapter(registry: RegistryRecord, key: string): ChapterRecord;
+    validateRegistry(value: unknown): RegistryRecord;
+    read(): Promise<RegistryRecord>;
+    persist(registry: RegistryRecord): Promise<void>;
+    atomic(name: string, value: unknown): Promise<void>;
+    lock<T>(fn: () => Promise<T>): Promise<T>;
+    walk(scopes?: string[], limit?: number): Promise<{
+        files: string[];
+        truncated: boolean;
+    }>;
+    sourceHash(relative: string): Promise<string>;
+    snapshot(pillar: Pick<ChapterRecord, 'paths' | 'facts'>, cache?: Map<string, Promise<string>>): Promise<Record<string, string>>;
+    validateFacts(pillar: Pick<ChapterRecord, 'paths' | 'facts'>): Promise<void>;
+    facts(registry: RegistryRecord): {
+        key: string;
+        chapterId: string;
+        chapter: {
+            id: string;
+            title: string;
+            scope: string;
+            excludes: string;
+            paths: string[];
+            revision: number;
+            facts: {
+                id: string;
+                statement: string;
+                evidence: {
+                    path: string;
+                    quote: string;
+                }[];
+                sourceScope: string[];
+                dependsOn: string[];
+            }[];
+            sources: Record<string, string>;
+            dependencyFingerprints: Record<string, string>;
+        };
+        fact: {
+            id: string;
+            statement: string;
+            evidence: {
+                path: string;
+                quote: string;
+            }[];
+            sourceScope: string[];
+            dependsOn: string[];
+        };
+    }[];
+    fact(registry: RegistryRecord, key: string): {
+        key: string;
+        chapterId: string;
+        chapter: {
+            id: string;
+            title: string;
+            scope: string;
+            excludes: string;
+            paths: string[];
+            revision: number;
+            facts: {
+                id: string;
+                statement: string;
+                evidence: {
+                    path: string;
+                    quote: string;
+                }[];
+                sourceScope: string[];
+                dependsOn: string[];
+            }[];
+            sources: Record<string, string>;
+            dependencyFingerprints: Record<string, string>;
+        };
+        fact: {
+            id: string;
+            statement: string;
+            evidence: {
+                path: string;
+                quote: string;
+            }[];
+            sourceScope: string[];
+            dependsOn: string[];
+        };
+    };
+    impact(registry: RegistryRecord, key: string, factIds?: string[]): string[];
+    related(registry: RegistryRecord, key: string, factIds?: string[]): string[];
+    upstreamFacts(registry: RegistryRecord, key: string, index?: Map<string, {
+        key: string;
+        chapterId: string;
+        chapter: {
+            id: string;
+            title: string;
+            scope: string;
+            excludes: string;
+            paths: string[];
+            revision: number;
+            facts: {
+                id: string;
+                statement: string;
+                evidence: {
+                    path: string;
+                    quote: string;
+                }[];
+                sourceScope: string[];
+                dependsOn: string[];
+            }[];
+            sources: Record<string, string>;
+            dependencyFingerprints: Record<string, string>;
+        };
+        fact: {
+            id: string;
+            statement: string;
+            evidence: {
+                path: string;
+                quote: string;
+            }[];
+            sourceScope: string[];
+            dependsOn: string[];
+        };
+    }>): string[];
+    dependencyFingerprints(registry: RegistryRecord, key: string): {
+        [k: string]: string;
+    };
+    context(registry: RegistryRecord, keys: string[], cache?: Map<string, Promise<string>>): Promise<Record<string, unknown>>;
+    status(key: string, registry?: RegistryRecord, cache?: Map<string, Promise<string>>): Promise<{
+        chapterId: string;
+        revision: number;
+        status: string;
+        locallyReviewed: boolean;
+        changedPaths: string[];
+        dependencyDrift: boolean;
+        error?: undefined;
+    } | {
+        chapterId: string;
+        revision: number;
+        status: string;
+        error: any;
+        locallyReviewed?: undefined;
+        changedPaths?: undefined;
+        dependencyDrift?: undefined;
+    }>;
+    migrate(): Promise<{
+        migrated: boolean;
+        pillars?: undefined;
+        backup?: undefined;
+    } | {
+        migrated: boolean;
+        pillars: number;
+        backup: string;
+    }>;
+    approveDefinitions(definitions: Definition[], standaloneReason?: string): Promise<{
+        schemaVersion: 2;
+        pillars: {
+            id: string;
+            title: string;
+            scope: string;
+            excludes: string;
+            chapters: {
+                id: string;
+                title: string;
+                scope: string;
+                excludes: string;
+                paths: string[];
+                revision: number;
+                facts: {
+                    id: string;
+                    statement: string;
+                    evidence: {
+                        path: string;
+                        quote: string;
+                    }[];
+                    sourceScope: string[];
+                    dependsOn: string[];
+                }[];
+                sources: Record<string, string>;
+                dependencyFingerprints: Record<string, string>;
+            }[];
+        }[];
+    }>;
+    addChapters(pillarId: string, definitions: unknown[]): Promise<{
+        id: string;
+        title: string;
+        scope: string;
+        excludes: string;
+        chapters: {
+            id: string;
+            title: string;
+            scope: string;
+            excludes: string;
+            paths: string[];
+            revision: number;
+            facts: {
+                id: string;
+                statement: string;
+                evidence: {
+                    path: string;
+                    quote: string;
+                }[];
+                sourceScope: string[];
+                dependsOn: string[];
+            }[];
+            sources: Record<string, string>;
+            dependencyFingerprints: Record<string, string>;
+        }[];
+    }>;
+    /** Validate an entire initial map or empty-chapter batch before one shared write. */
+    bootstrap(definitions: Definition[] | undefined, batches: {
+        chapterId: string;
+        facts: unknown[];
+    }[], dryRun: boolean, expected?: string): Promise<{
+        dryRun: boolean;
+        validation: string;
+        preflight: string;
+        approvalRequired: boolean | {
+            boundaries: boolean;
+            facts: boolean;
+        };
+        approved: {
+            boundaries: boolean;
+            facts: boolean;
+            content: string;
+            declarationOnly: boolean;
+            humanReviewVerified: boolean;
+        } | undefined;
+        chapters: string[];
+        factCount: number;
+        sourceFileCounts: Record<string, number>;
+        outputPath: string;
+        next: string;
+    }>;
+    seed(key: string, facts: unknown): Promise<{
+        id: string;
+        title: string;
+        scope: string;
+        excludes: string;
+        paths: string[];
+        revision: number;
+        facts: {
+            id: string;
+            statement: string;
+            evidence: {
+                path: string;
+                quote: string;
+            }[];
+            sourceScope: string[];
+            dependsOn: string[];
+        }[];
+        sources: Record<string, string>;
+        dependencyFingerprints: Record<string, string>;
+    }>;
+    admit(key: string, additions: unknown): Promise<{
+        id: string;
+        title: string;
+        scope: string;
+        excludes: string;
+        paths: string[];
+        revision: number;
+        facts: {
+            id: string;
+            statement: string;
+            evidence: {
+                path: string;
+                quote: string;
+            }[];
+            sourceScope: string[];
+            dependsOn: string[];
+        }[];
+        sources: Record<string, string>;
+        dependencyFingerprints: Record<string, string>;
+    }>;
+    reviewPlan(key: string, factIds?: string[]): Promise<{
+        chapterId: string;
+        factIds: string[] | undefined;
+        policy: string;
+        affectedFacts: string[];
+        chapters: {
+            chapterId: string;
+            title: string;
+            revision: number;
+            factCount: number;
+            freshness: {
+                chapterId: string;
+                revision: number;
+                status: string;
+                locallyReviewed: boolean;
+                changedPaths: string[];
+                dependencyDrift: boolean;
+                error?: undefined;
+            } | {
+                chapterId: string;
+                revision: number;
+                status: string;
+                error: any;
+                locallyReviewed?: undefined;
+                changedPaths?: undefined;
+                dependencyDrift?: undefined;
+            };
+        }[];
+    }>;
+    resolveTarget(registry: RegistryRecord, target: string): string[];
+    requestTidy(target: string | string[], expectedRegistry?: RegistryRecord): Promise<{
+        tidyId: null;
+        instruction: string;
+        requiredChapters?: undefined;
+    } | {
+        tidyId: `${string}-${string}-${string}-${string}-${string}`;
+        requiredChapters: string[];
+        instruction: string;
+    }>;
+    tidyScope(id: string, registry: RegistryRecord): Promise<string[]>;
+    reviewFiles(registry: RegistryRecord, keys: string[], touchedPaths: string[], candidate?: {
+        schemaVersion: 2;
+        pillars: {
+            id: string;
+            title: string;
+            scope: string;
+            excludes: string;
+            chapters: {
+                id: string;
+                title: string;
+                scope: string;
+                excludes: string;
+                paths: string[];
+                revision: number;
+                facts: {
+                    id: string;
+                    statement: string;
+                    evidence: {
+                        path: string;
+                        quote: string;
+                    }[];
+                    sourceScope: string[];
+                    dependsOn: string[];
+                }[];
+                sources: Record<string, string>;
+                dependencyFingerprints: Record<string, string>;
+            }[];
+        }[];
+    }): Promise<{
+        sourceFiles: string[];
+        documentFiles: string[];
+    }>;
+    fileSnapshots(files: string[]): Promise<Record<string, string>>;
+    evaluate(input: UpdateRequest, registry: RegistryRecord): Promise<{
+        request: {
+            chapterId: string;
+            touchedPaths: string[];
+            reviews: {
+                facts: {
+                    id: string;
+                    statement: string;
+                    evidence: {
+                        path: string;
+                        quote: string;
+                    }[];
+                    sourceScope: string[];
+                    dependsOn: string[];
+                }[];
+                reason: string;
+                chapterId: string;
+                expectedRevision: number;
+                invalidatedFactIds: string[];
+                reviewedFactIds: string[];
+                maintenance?: {
+                    factId: string;
+                    action: "correct" | "merge" | "remove" | "tighten";
+                    reason: string;
+                    replacement?: string | undefined;
+                }[] | undefined;
+            }[];
+            verification: {
+                sourceFiles: string[];
+                documentFiles: string[];
+            };
+            factIds?: string[] | undefined;
+            tidyId?: string | undefined;
+        };
+        required: string[];
+        snapshots: Record<string, Record<string, string>>;
+        reviewSnapshots: Record<string, string>;
+        changed: string[];
+    }>;
+    markReviewed(registry: RegistryRecord, keys: string[], snapshots: Record<string, Record<string, string>>): Promise<void>;
+    prepare(input: UpdateRequest): Promise<{
+        noop: true;
+        proposalId?: undefined;
+        changedChapters?: undefined;
+        reviewedChapters?: undefined;
+    } | {
+        noop: false;
+        proposalId: `${string}-${string}-${string}-${string}-${string}`;
+        changedChapters: string[];
+        reviewedChapters: string[];
+    }>;
+    commit(id: string): Promise<{
+        changedChapters: string[];
+        reviewedChapters: string[];
+    }>;
+}