@unson/brainbase-mcp 0.6.0 → 0.8.0

package/dist/graph-web.d.ts

@@ -0,0 +1,364 @@
+import { GRAPH_CORRECTIONS_FILE, type GraphCorrectionRecord } from './graph-corrections.js';
+import { type PortableGraphOwner } from './portable-graph.js';
+import type { FoundationAdoptionState, FoundationOperator } from './ontology-foundation.js';
+import type { CanonicalEdge, CanonicalEntityKind, CoreRelation } from './types.js';
+/**
+ * Read views of the canonical local Graph for the local Web screens
+ * "プロジェクトと関係者" and "情報と関係".
+ *
+ * Every function takes an explicit data directory chosen by the host, never by
+ * the browser. A Graph v1 file is reported as `migration_required` and a
+ * missing data set as `not_initialized`; neither is presented as zero items,
+ * and a read failure is thrown instead of being returned as an empty list.
+ *
+ * `openOwnerPrivateGraph` gives the same read views over a portable bundle a
+ * host keeps for its owner (the owner-private area), without a data directory.
+ */
+export declare const GRAPH_WEB_VERSION: "graph-web.v1";
+export declare const GRAPH_WEB_START_COMMAND = "brainbase onboard:start";
+export declare const GRAPH_WEB_SEARCH_MAX_LIMIT = 100;
+/** The kinds of record a Graph v2 can hold; any other kind is absent from it. */
+export declare const GRAPH_WEB_ENTITY_KINDS: readonly CanonicalEntityKind[];
+declare const ONBOARDING_LEDGER_FILE = "runs/connected-onboarding.json";
+export interface GraphWebSource {
+    dataDir: string;
+    graphFormat: 1 | 2 | null;
+    authority: 'local_graph';
+}
+/**
+ * A portable bundle a host keeps for its owner: the owner's own records, not
+ * the host's shared Graph.  There is no data directory.
+ */
+export interface GraphWebOwnerPrivateSource {
+    dataDir: null;
+    graphFormat: 2;
+    authority: 'owner_private';
+}
+export type GraphWebAnySource = GraphWebSource | GraphWebOwnerPrivateSource;
+export interface GraphMigrationRequired {
+    status: 'migration_required';
+    source: GraphWebSource;
+    /** Entities in the Graph v1 file. They exist but cannot be shown or corrected until migrated. */
+    legacyEntityCount: number;
+    /** Preview first; it prints the expectedInputDigest the write step needs. */
+    command: string;
+    writeCommand: string;
+    message: string;
+    absenceConfirmed: false;
+}
+export interface GraphNotInitialized {
+    status: 'not_initialized';
+    source: GraphWebSource;
+    command: typeof GRAPH_WEB_START_COMMAND;
+    message: string;
+    /** No canonical file exists in the data directory, so nothing is registered. */
+    absenceConfirmed: true;
+}
+export type GraphWebUnavailable = GraphMigrationRequired | GraphNotInitialized;
+export interface GraphReadIssue {
+    file: string;
+    line?: number;
+    reason: string;
+}
+export interface GraphEntityView {
+    id: string;
+    type: CanonicalEntityKind;
+    name: string;
+    aliases: string[];
+    summary: string | null;
+    tags: string[];
+    validFrom: string | null;
+    validTo: string | null;
+    /** Active at the response `asOf`. */
+    active: boolean;
+    digest: string;
+    goal?: string | null;
+    status?: string | null;
+}
+export type GraphProvenanceReference = {
+    status: 'none';
+} | {
+    status: 'unresolved';
+    sourceId: string;
+} | {
+    status: 'resolved';
+    kind: 'extracted_candidate';
+    file: string;
+    candidateId: string;
+    candidateKind: string | null;
+    label: string | null;
+} | {
+    status: 'resolved';
+    kind: 'onboarding_run_candidate';
+    file: typeof ONBOARDING_LEDGER_FILE;
+    runId: string;
+    candidateId: string;
+    candidateKind: string | null;
+    reviewStatus: string | null;
+    label: string | null;
+} | {
+    status: 'resolved';
+    kind: 'graph_correction';
+    file: typeof GRAPH_CORRECTIONS_FILE;
+    correctionId: string;
+    at: string;
+    reason: string;
+};
+export interface GraphProvenanceView {
+    sourceKind: NonNullable<CanonicalEdge['provenance']>['sourceKind'] | null;
+    sourceId: string | null;
+    evidenceHash: string | null;
+    reference: GraphProvenanceReference;
+}
+export interface GraphEdgeView {
+    id: string;
+    relation: CoreRelation;
+    meaning: string;
+    direction: 'incoming' | 'outgoing';
+    fromId: string;
+    toId: string;
+    role: string | null;
+    context: string | null;
+    validFrom: string | null;
+    validTo: string | null;
+    active: boolean;
+    provenance: GraphProvenanceView;
+    counterpart: {
+        id: string;
+        type: CanonicalEntityKind;
+        name: string;
+        active: boolean;
+        digest: string;
+    };
+    digest: string;
+}
+export interface GraphWebStatus {
+    status: 'ok';
+    version: typeof GRAPH_WEB_VERSION;
+    source: GraphWebSource;
+    asOf: string;
+    ontology: {
+        id: string;
+        version: string;
+        releaseDigest: string;
+        currentVersion: string;
+    };
+    counts: {
+        entities: Record<CanonicalEntityKind, number> & {
+            total: number;
+        };
+        edges: {
+            total: number;
+            active: number;
+        };
+        relationships: number;
+        corrections: number;
+    };
+    issues: GraphReadIssue[];
+}
+export interface GraphProjectPersonView {
+    id: string;
+    name: string;
+    /** True when one of the person's active relations to the project is accountable_for. */
+    accountable: boolean;
+}
+export interface GraphProjectListItem extends GraphEntityView {
+    type: 'project';
+    goal: string | null;
+    status: string | null;
+    /** Distinct people with an active participates_in or accountable_for relation. */
+    participantCount: number;
+    accountableCount: number;
+    /** The same people by name, accountable first, so a list can name them and count them across projects. */
+    people: GraphProjectPersonView[];
+}
+export interface GraphProjectList<S extends GraphWebAnySource = GraphWebSource> {
+    status: 'ok';
+    source: S;
+    asOf: string;
+    projects: GraphProjectListItem[];
+    /** True only when the readable Graph v2 holds no project at all. */
+    absenceConfirmed: boolean;
+}
+export interface GraphProjectDetail<S extends GraphWebAnySource = GraphWebSource> {
+    status: 'ok';
+    source: S;
+    asOf: string;
+    project: GraphEntityView & {
+        type: 'project';
+        goal: string | null;
+        status: string | null;
+        decisionPrinciples: string[];
+        metadata: Record<string, unknown>;
+    };
+    /** Incoming participates_in / accountable_for relations, including ended ones. */
+    participants: GraphEdgeView[];
+    /** Other relations of the project (governs, owned_by, ...). */
+    relations: GraphEdgeView[];
+    history: GraphCorrectionRecord[];
+    issues: GraphReadIssue[];
+}
+export interface GraphEntitySearchInput {
+    q?: string;
+    type?: string;
+    asOf?: string;
+    limit?: number;
+    /** Used for each result's `active` flag when no as_of filter is given. */
+    now?: Date;
+}
+export interface GraphEntitySearchResult<S extends GraphWebAnySource = GraphWebSource> {
+    status: 'ok';
+    source: S;
+    query: {
+        q: string;
+        type: CanonicalEntityKind | null;
+        asOf: string | null;
+    };
+    results: GraphEntityView[];
+    total: number;
+    truncated: boolean;
+    /**
+     * True when the whole readable Graph v2 was scanned and nothing matched the
+     * name/alias query and filters. Never true for Graph v1 or a read failure.
+     */
+    absenceConfirmed: boolean;
+    /** True when the Graph v2 holds no entity at all (show "まだ登録がありません"). */
+    graphEmpty: boolean;
+}
+export interface GraphEntityDetail<S extends GraphWebAnySource = GraphWebSource> {
+    status: 'ok';
+    source: S;
+    asOf: string;
+    entity: GraphEntityView & {
+        metadata: Record<string, unknown>;
+    };
+    outgoing: GraphEdgeView[];
+    incoming: GraphEdgeView[];
+    history: GraphCorrectionRecord[];
+    issues: GraphReadIssue[];
+    /**
+     * For a decision of a portable bundle: its judgment record (判断根拠) from
+     * the bundle's decisions, or null when the bundle has none for it.
+     */
+    decisionRecord?: GraphDecisionRecordView | null;
+}
+export interface GraphDecisionRecordView {
+    title: string;
+    decision: string;
+    rationale: string | null;
+    topic: string | null;
+    effectiveAt: string | null;
+    supersedes: string[];
+}
+/** A person named by an objective, with the name of their record in the same Graph (null when it has none). */
+export interface GraphObjectivePersonView {
+    id: string;
+    name: string | null;
+}
+/** The latest revision of an objective defined in a Graph's foundation. */
+export interface GraphObjectiveView {
+    id: string;
+    revision: string;
+    meaning: string;
+    desiredState: string;
+    adoptionState: FoundationAdoptionState;
+    evaluationPeriod: {
+        from: string;
+        until: string;
+    };
+    criteria: Array<{
+        variable: {
+            id: string;
+            revision: string;
+            meaning: string | null;
+            unit: string | null;
+        };
+        operator: FoundationOperator;
+        target: string | number | boolean | null;
+    }>;
+    accountable: GraphObjectivePersonView | null;
+    beneficiaries: GraphObjectivePersonView[];
+    visibility: string;
+}
+export interface GraphObjectiveList<S extends GraphWebAnySource = GraphWebSource> {
+    status: 'ok';
+    source: S;
+    objectives: GraphObjectiveView[];
+    /** `none` when the Graph has no foundation at all. */
+    foundation: 'none' | 'ok';
+    /** True when the foundation was read and holds no objective. */
+    absenceConfirmed: boolean;
+}
+export interface GraphOntologySummary {
+    status: 'ok';
+    source: GraphWebSource;
+    asOf: string;
+    ontology: {
+        id: string;
+        version: string;
+        releaseDigest: string;
+        currentVersion: string;
+        upToDate: boolean;
+    };
+    entityTypes: Array<{
+        id: CanonicalEntityKind;
+        meaning: string;
+        count: number;
+    }>;
+    relations: Array<{
+        id: CoreRelation;
+        from: CanonicalEntityKind;
+        to: CanonicalEntityKind;
+        meaning: string;
+        count: number;
+        activeCount: number;
+    }>;
+    corrections: {
+        entityFields: readonly string[];
+        projectFields: readonly string[];
+        edgeFields: readonly string[];
+        newEdgeRelations: readonly string[];
+    };
+}
+export type GraphWebErrorKind = 'invalid' | 'not_found' | 'unavailable';
+export declare class GraphWebError extends Error {
+    readonly kind: GraphWebErrorKind;
+    readonly code: string;
+    readonly name = "GraphWebError";
+    constructor(kind: GraphWebErrorKind, code: string, message: string);
+}
+export interface GraphWebReadOptions {
+    asOf?: string;
+    now?: Date;
+}
+export declare function readGraphWebStatus(dataDir: string, options?: GraphWebReadOptions): Promise<GraphWebStatus | GraphWebUnavailable>;
+export declare function listGraphProjects(dataDir: string, options?: GraphWebReadOptions): Promise<GraphProjectList | GraphWebUnavailable>;
+export declare function readGraphProject(dataDir: string, projectId: string, options?: GraphWebReadOptions): Promise<GraphProjectDetail | GraphWebUnavailable>;
+export declare function searchGraphEntities(dataDir: string, input?: GraphEntitySearchInput): Promise<GraphEntitySearchResult | GraphWebUnavailable>;
+export declare function readGraphEntity(dataDir: string, entityId: string, options?: GraphWebReadOptions): Promise<GraphEntityDetail | GraphWebUnavailable>;
+export declare function readGraphOntology(dataDir: string, options?: GraphWebReadOptions): Promise<GraphOntologySummary | GraphWebUnavailable>;
+/** The source of every read view of an owner-private snapshot. */
+export declare const GRAPH_WEB_OWNER_PRIVATE_SOURCE: Readonly<GraphWebOwnerPrivateSource>;
+/** Read views of one owner-private snapshot, the same shapes as the local Graph routes. */
+export interface OwnerPrivateGraph {
+    readonly source: GraphWebOwnerPrivateSource;
+    listProjects(options?: GraphWebReadOptions): GraphProjectList<GraphWebOwnerPrivateSource>;
+    readProject(projectId: string, options?: GraphWebReadOptions): GraphProjectDetail<GraphWebOwnerPrivateSource>;
+    search(input?: GraphEntitySearchInput): GraphEntitySearchResult<GraphWebOwnerPrivateSource>;
+    readEntity(entityId: string, options?: GraphWebReadOptions): GraphEntityDetail<GraphWebOwnerPrivateSource>;
+    /** Throws `foundation_invalid` when the bundle's foundation does not pass the catalog check. */
+    listObjectives(options?: GraphWebReadOptions): GraphObjectiveList<GraphWebOwnerPrivateSource>;
+}
+/**
+ * Opens a portable bundle a host keeps for its owner, read as that owner
+ * (`bindPortableGraphOwner`: `self` becomes the owner's person ID and name).
+ *
+ * The bundle is checked with `validatePortableGraph` first
+ * (`portable_graph_invalid` otherwise).  Its foundation is checked on its own
+ * (the Graph check ignores it): a foundation that does not pass fails only the
+ * objectives view.  Nothing is written anywhere, and relation sources
+ * (candidate files, the onboarding ledger, corrections) stayed on the owner's
+ * machine, so a relation's source ID is shown unresolved.
+ */
+export declare function openOwnerPrivateGraph(bundle: unknown, owner: PortableGraphOwner): OwnerPrivateGraph;
+export {};