@unson/brainbase-mcp 0.7.0 → 0.9.0

package/dist/graph-web.js

@@ -0,0 +1,639 @@
+import { access, readdir, readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { isActiveAt } from './canonical-graph.js';
+import { assertFoundationCatalog, findFoundationRecord } from './foundation-catalog.js';
+import { GRAPH_CORRECTION_EDGE_FIELDS, GRAPH_CORRECTION_ENTITY_FIELDS, GRAPH_CORRECTION_NEW_EDGE_RELATIONS, GRAPH_CORRECTION_PROJECT_FIELDS, GRAPH_CORRECTIONS_FILE, graphRecordDigest, readGraphCorrectionHistory } from './graph-corrections.js';
+import { ONTOLOGY_VERSION, portableOntology } from './ontology.js';
+import { canonicalRelationRegistry, getCanonicalRelation } from './relation-registry.js';
+import { loadPersonalOs } from './ssot.js';
+import { bindPortableGraphOwner, validatePortableGraph } from './portable-graph.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 const GRAPH_WEB_VERSION = 'graph-web.v1';
+export const GRAPH_WEB_START_COMMAND = 'brainbase onboard:start';
+export const GRAPH_WEB_SEARCH_MAX_LIMIT = 100;
+const CANONICAL_FILES = ['graph.json', 'relationships.json', 'personal-kg.jsonl', 'decisions.jsonl'];
+const ENTITY_KINDS = ['person', 'org', 'project', 'decision'];
+/** The kinds of record a Graph v2 can hold; any other kind is absent from it. */
+export const GRAPH_WEB_ENTITY_KINDS = ENTITY_KINDS;
+const PARTICIPATION = new Set(['participates_in', 'accountable_for']);
+const EXTRACTED_CANDIDATE_FILE = /^extracted-[^/\\]+\.json$/u;
+const ONBOARDING_LEDGER_FILE = 'runs/connected-onboarding.json';
+const ONBOARDING_LEDGER_SCHEMA = 'connected_onboarding.v1';
+export class GraphWebError extends Error {
+    kind;
+    code;
+    name = 'GraphWebError';
+    constructor(kind, code, message) {
+        super(message);
+        this.kind = kind;
+        this.code = code;
+    }
+}
+export async function readGraphWebStatus(dataDir, options = {}) {
+    const loaded = await loadForRead(dataDir);
+    if ('status' in loaded)
+        return loaded;
+    const asOf = resolveAsOf(options);
+    const { graph } = loaded;
+    const entities = Object.fromEntries(ENTITY_KINDS.map((kind) => [kind, graph.entities.filter((entity) => entity.type === kind).length]));
+    const history = await readGraphCorrectionHistory(dataDir);
+    return {
+        status: 'ok',
+        version: GRAPH_WEB_VERSION,
+        source: loaded.source,
+        asOf,
+        ontology: { ...graph.ontology, currentVersion: ONTOLOGY_VERSION },
+        counts: {
+            entities: { ...entities, total: graph.entities.length },
+            edges: { total: graph.edges.length, active: graph.edges.filter((edge) => isActiveAt(edge, asOf)).length },
+            relationships: loaded.os.relationships.relationships.length,
+            corrections: history.records.length
+        },
+        issues: history.issues
+    };
+}
+export async function listGraphProjects(dataDir, options = {}) {
+    const loaded = await loadForRead(dataDir);
+    if ('status' in loaded)
+        return loaded;
+    return projectListOf(loaded.graph, loaded.source, resolveAsOf(options));
+}
+function projectListOf(graph, source, asOf) {
+    const entities = entityIndex(graph);
+    const projects = graph.entities.filter((entity) => entity.type === 'project').map((project) => {
+        const participation = graph.edges.filter((edge) => edge.toId === project.id && PARTICIPATION.has(edge.relation)
+            && isActiveAt(edge, asOf) && isEntityActive(entities.get(edge.fromId), asOf));
+        const byPerson = new Map();
+        for (const edge of participation) {
+            const person = byPerson.get(edge.fromId) ?? { id: edge.fromId, name: entities.get(edge.fromId)?.name ?? edge.fromId, accountable: false };
+            if (edge.relation === 'accountable_for')
+                person.accountable = true;
+            byPerson.set(edge.fromId, person);
+        }
+        const people = [...byPerson.values()].sort((left, right) => Number(right.accountable) - Number(left.accountable)
+            || left.name.localeCompare(right.name, 'ja')
+            || left.id.localeCompare(right.id, 'en'));
+        return {
+            ...projectView(project, asOf),
+            participantCount: people.length,
+            accountableCount: people.filter((person) => person.accountable).length,
+            people
+        };
+    }).sort(byActiveThenName);
+    return { status: 'ok', source, asOf, projects, absenceConfirmed: projects.length === 0 };
+}
+export async function readGraphProject(dataDir, projectId, options = {}) {
+    const loaded = await loadForRead(dataDir);
+    if ('status' in loaded)
+        return loaded;
+    const asOf = resolveAsOf(options);
+    if (!loaded.graph.entities.some((entity) => entity.id === projectId && entity.type === 'project')) {
+        throw new GraphWebError('not_found', 'project_not_found', `No project ${projectId}`);
+    }
+    return projectDetailOf(loaded.graph, loaded.source, projectId, asOf, await loadReferences(dataDir));
+}
+function projectDetailOf(graph, source, projectId, asOf, references) {
+    const project = graph.entities.find((entity) => entity.id === projectId && entity.type === 'project');
+    if (!project)
+        throw new GraphWebError('not_found', 'project_not_found', `No project ${projectId}`);
+    const entities = entityIndex(graph);
+    const edges = incidentEdges(graph, project.id, asOf, entities, references);
+    const participants = edges.filter((edge) => edge.direction === 'incoming' && PARTICIPATION.has(edge.relation)).sort(byParticipation);
+    const relations = edges.filter((edge) => !participants.includes(edge));
+    const touched = new Set([project.id, ...edges.map((edge) => edge.id)]);
+    return {
+        status: 'ok',
+        source,
+        asOf,
+        project: {
+            ...projectView(project, asOf),
+            decisionPrinciples: stringArray(project.metadata?.decisionPrinciples),
+            metadata: project.metadata ?? {}
+        },
+        participants,
+        relations,
+        history: historyFor(references.history, touched),
+        issues: references.issues
+    };
+}
+export async function searchGraphEntities(dataDir, input = {}) {
+    const query = parseSearchInput(input);
+    const loaded = await loadForRead(dataDir);
+    if ('status' in loaded)
+        return loaded;
+    return entitySearchOf(loaded.graph, loaded.source, query);
+}
+function parseSearchInput(input) {
+    const q = typeof input.q === 'string' ? input.q.trim() : '';
+    if (q.length > 200)
+        throw new GraphWebError('invalid', 'invalid_query', 'q must be at most 200 characters');
+    const type = parseEntityType(input.type);
+    const asOf = input.asOf === undefined || input.asOf === '' ? null : parseAsOf(input.asOf);
+    const limit = input.limit ?? 50;
+    if (!Number.isInteger(limit) || limit < 1 || limit > GRAPH_WEB_SEARCH_MAX_LIMIT) {
+        throw new GraphWebError('invalid', 'invalid_query', `limit must be an integer from 1 to ${GRAPH_WEB_SEARCH_MAX_LIMIT}`);
+    }
+    return { q, type, asOf, limit, now: input.now };
+}
+function entitySearchOf(graph, source, { q, type, asOf, limit, now }) {
+    const needle = normalize(q);
+    const scored = graph.entities.flatMap((entity) => {
+        if (type && entity.type !== type)
+            return [];
+        if (asOf && !isActiveAt(entity, asOf))
+            return [];
+        const rank = matchRank(entity, needle);
+        return rank === undefined ? [] : [{ entity, rank }];
+    }).sort((left, right) => left.rank - right.rank
+        || left.entity.type.localeCompare(right.entity.type, 'en')
+        || left.entity.name.localeCompare(right.entity.name, 'ja')
+        || left.entity.id.localeCompare(right.entity.id, 'en'));
+    const viewAsOf = asOf ?? (now ?? new Date()).toISOString();
+    const results = scored.slice(0, limit).map(({ entity }) => entityView(entity, viewAsOf));
+    return {
+        status: 'ok',
+        source,
+        query: { q, type, asOf },
+        results,
+        total: scored.length,
+        truncated: scored.length > results.length,
+        absenceConfirmed: scored.length === 0,
+        graphEmpty: graph.entities.length === 0
+    };
+}
+export async function readGraphEntity(dataDir, entityId, options = {}) {
+    const loaded = await loadForRead(dataDir);
+    if ('status' in loaded)
+        return loaded;
+    const asOf = resolveAsOf(options);
+    uniqueEntity(loaded.graph, entityId, 'graph.json');
+    return entityDetailOf(loaded.graph, loaded.source, entityId, asOf, await loadReferences(dataDir));
+}
+function uniqueEntity(graph, entityId, where) {
+    const matches = graph.entities.filter((candidate) => candidate.id === entityId);
+    if (matches.length === 0)
+        throw new GraphWebError('not_found', 'entity_not_found', `No entity ${entityId}`);
+    if (matches.length > 1)
+        throw new GraphWebError('unavailable', 'entity_id_ambiguous', `Entity id ${entityId} is duplicated in ${where}`);
+    return matches[0];
+}
+function entityDetailOf(graph, source, entityId, asOf, references) {
+    const entity = uniqueEntity(graph, entityId, 'the Graph');
+    const edges = incidentEdges(graph, entity.id, asOf, entityIndex(graph), references);
+    const touched = new Set([entity.id, ...edges.map((edge) => edge.id)]);
+    return {
+        status: 'ok',
+        source,
+        asOf,
+        entity: { ...entityView(entity, asOf), metadata: entity.metadata ?? {} },
+        outgoing: edges.filter((edge) => edge.direction === 'outgoing'),
+        incoming: edges.filter((edge) => edge.direction === 'incoming'),
+        history: historyFor(references.history, touched),
+        issues: references.issues
+    };
+}
+export async function readGraphOntology(dataDir, options = {}) {
+    const loaded = await loadForRead(dataDir);
+    if ('status' in loaded)
+        return loaded;
+    const asOf = resolveAsOf(options);
+    const { graph } = loaded;
+    const concepts = new Map(portableOntology.domains.types.concepts.map((concept) => [concept.id, concept.meaning]));
+    return {
+        status: 'ok',
+        source: loaded.source,
+        asOf,
+        ontology: { ...graph.ontology, currentVersion: ONTOLOGY_VERSION, upToDate: graph.ontology.version === ONTOLOGY_VERSION },
+        entityTypes: ENTITY_KINDS.map((kind) => ({
+            id: kind,
+            meaning: concepts.get(kind) ?? '',
+            count: graph.entities.filter((entity) => entity.type === kind).length
+        })),
+        relations: Object.values(canonicalRelationRegistry).map((definition) => {
+            const edges = graph.edges.filter((edge) => edge.relation === definition.id);
+            return {
+                id: definition.id,
+                from: definition.from,
+                to: definition.to,
+                meaning: definition.meaning,
+                count: edges.length,
+                activeCount: edges.filter((edge) => isActiveAt(edge, asOf)).length
+            };
+        }),
+        corrections: {
+            entityFields: GRAPH_CORRECTION_ENTITY_FIELDS,
+            projectFields: GRAPH_CORRECTION_PROJECT_FIELDS,
+            edgeFields: GRAPH_CORRECTION_EDGE_FIELDS,
+            newEdgeRelations: GRAPH_CORRECTION_NEW_EDGE_RELATIONS
+        }
+    };
+}
+// ---------------------------------------------------------------------------
+// Owner-private snapshots
+/** The source of every read view of an owner-private snapshot. */
+export const GRAPH_WEB_OWNER_PRIVATE_SOURCE = Object.freeze({ dataDir: null, graphFormat: 2, authority: 'owner_private' });
+const NO_REFERENCES = Object.freeze({
+    extracted: new Map(),
+    onboarding: new Map(),
+    history: [],
+    corrections: new Map(),
+    issues: []
+});
+/**
+ * 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 function openOwnerPrivateGraph(bundle, owner) {
+    try {
+        validatePortableGraph(bundle);
+    }
+    catch (error) {
+        throw new GraphWebError('unavailable', 'portable_graph_invalid', errorMessage(error));
+    }
+    let foundationError = null;
+    try {
+        assertFoundationCatalog(bundle.graph.foundation);
+    }
+    catch (error) {
+        foundationError = errorMessage(error);
+    }
+    let bound;
+    try {
+        bound = bindPortableGraphOwner(bundle, owner);
+    }
+    catch (error) {
+        throw new GraphWebError('unavailable', 'portable_graph_owner_conflict', errorMessage(error));
+    }
+    const graph = bound.graph;
+    const source = GRAPH_WEB_OWNER_PRIVATE_SOURCE;
+    const decisions = new Map(bound.decisions.map((record) => [record.id, record]));
+    return Object.freeze({
+        source,
+        listProjects: (options = {}) => projectListOf(graph, source, resolveAsOf(options)),
+        readProject: (projectId, options = {}) => projectDetailOf(graph, source, projectId, resolveAsOf(options), NO_REFERENCES),
+        search: (input = {}) => entitySearchOf(graph, source, parseSearchInput(input)),
+        readEntity: (entityId, options = {}) => {
+            const detail = entityDetailOf(graph, source, entityId, resolveAsOf(options), NO_REFERENCES);
+            if (detail.entity.type !== 'decision')
+                return detail;
+            const record = decisions.get(entityId);
+            return { ...detail, decisionRecord: record ? decisionRecordView(record) : null };
+        },
+        listObjectives: () => {
+            if (foundationError !== null)
+                throw new GraphWebError('unavailable', 'foundation_invalid', foundationError);
+            return objectiveListOf(graph, source);
+        }
+    });
+}
+function decisionRecordView(record) {
+    return {
+        title: record.title,
+        decision: record.decision,
+        rationale: record.rationale ?? null,
+        topic: record.topic ?? null,
+        effectiveAt: record.effectiveAt ?? null,
+        supersedes: record.supersedes ?? []
+    };
+}
+function objectiveListOf(graph, source) {
+    const catalog = graph.foundation;
+    if (!catalog)
+        return { status: 'ok', source, objectives: [], foundation: 'none', absenceConfirmed: true };
+    const entities = entityIndex(graph);
+    const person = (id) => ({ id, name: entities.get(id)?.name ?? null });
+    const objectives = Object.values(catalog.latest)
+        .filter((pointer) => pointer.type === 'objective')
+        .flatMap((pointer) => {
+        const definition = findFoundationRecord(catalog, pointer)?.definition;
+        if (!definition)
+            return [];
+        return [{
+                id: definition.id,
+                revision: definition.revision,
+                meaning: definition.meaning,
+                desiredState: definition.desiredState,
+                adoptionState: definition.adoptionState,
+                evaluationPeriod: { from: definition.evaluationPeriod.from, until: definition.evaluationPeriod.until },
+                criteria: definition.criteria.map((criterion) => {
+                    const variable = findFoundationRecord(catalog, criterion.variableRef)?.definition;
+                    return {
+                        variable: { id: criterion.variableRef.id, revision: criterion.variableRef.revision, meaning: variable?.meaning ?? null, unit: variable?.unit ?? null },
+                        operator: criterion.operator,
+                        target: criterion.target ?? null
+                    };
+                }),
+                accountable: definition.accountableId ? person(definition.accountableId) : null,
+                beneficiaries: definition.beneficiaryIds.map(person),
+                visibility: definition.acl.visibility
+            }];
+    })
+        .sort((left, right) => left.meaning.localeCompare(right.meaning, 'ja') || left.id.localeCompare(right.id, 'en'));
+    return { status: 'ok', source, objectives, foundation: 'ok', absenceConfirmed: objectives.length === 0 };
+}
+async function loadForRead(dataDir) {
+    if (typeof dataDir !== 'string' || dataDir.trim() === '')
+        throw new TypeError('dataDir is required');
+    const present = await Promise.all(CANONICAL_FILES.map((file) => exists(join(dataDir, file))));
+    if (!present.some(Boolean)) {
+        return {
+            status: 'not_initialized',
+            source: { dataDir, graphFormat: null, authority: 'local_graph' },
+            command: GRAPH_WEB_START_COMMAND,
+            message: 'No canonical Brainbase data exists in this data directory yet',
+            absenceConfirmed: true
+        };
+    }
+    let os;
+    try {
+        os = await loadPersonalOs(dataDir);
+    }
+    catch (error) {
+        throw new GraphWebError('unavailable', 'graph_unavailable', error instanceof Error ? error.message : String(error));
+    }
+    if (os.graph.version !== 2) {
+        const dir = shellArg(dataDir);
+        return {
+            status: 'migration_required',
+            source: { dataDir, graphFormat: 1, authority: 'local_graph' },
+            legacyEntityCount: os.graph.entities.length,
+            command: `brainbase ontology:migrate --dir ${dir}`,
+            writeCommand: `brainbase ontology:migrate --dir ${dir} --write --expected-input-digest <preview expectedInputDigest>`,
+            message: 'graph.json is Graph v1. Migrate it to Graph v2 with the CLI; this host never migrates automatically',
+            absenceConfirmed: false
+        };
+    }
+    return { os, graph: os.graph, source: { dataDir, graphFormat: 2, authority: 'local_graph' } };
+}
+async function loadReferences(dataDir) {
+    const issues = [];
+    const extracted = new Map();
+    let candidateFiles = [];
+    try {
+        candidateFiles = (await readdir(join(dataDir, 'candidates'))).filter((file) => EXTRACTED_CANDIDATE_FILE.test(file)).sort();
+    }
+    catch (error) {
+        if (errorCode(error) !== 'ENOENT')
+            issues.push({ file: 'candidates', reason: errorMessage(error) });
+    }
+    for (const name of candidateFiles) {
+        const file = `candidates/${name}`;
+        try {
+            const parsed = JSON.parse(await readFile(join(dataDir, file), 'utf8'));
+            const candidates = isRecord(parsed) && Array.isArray(parsed.candidates) ? parsed.candidates : undefined;
+            if (!candidates) {
+                issues.push({ file, reason: 'candidate file has no candidates array' });
+                continue;
+            }
+            for (const candidate of candidates) {
+                if (!isRecord(candidate) || typeof candidate.id !== 'string' || extracted.has(candidate.id))
+                    continue;
+                extracted.set(candidate.id, { file, kind: stringOrNull(candidate.kind), label: payloadLabel(candidate.payload) });
+            }
+        }
+        catch (error) {
+            issues.push({ file, reason: errorMessage(error) });
+        }
+    }
+    const onboarding = new Map();
+    try {
+        const parsed = JSON.parse(await readFile(join(dataDir, ONBOARDING_LEDGER_FILE), 'utf8'));
+        if (!isRecord(parsed) || parsed.schemaVersion !== ONBOARDING_LEDGER_SCHEMA || !Array.isArray(parsed.runs)) {
+            issues.push({ file: ONBOARDING_LEDGER_FILE, reason: 'unsupported connected onboarding ledger schema' });
+        }
+        else {
+            for (const run of parsed.runs) {
+                if (!isRecord(run) || typeof run.id !== 'string' || !Array.isArray(run.candidates))
+                    continue;
+                for (const candidate of run.candidates) {
+                    if (!isRecord(candidate) || typeof candidate.id !== 'string')
+                        continue;
+                    onboarding.set(candidate.id, {
+                        runId: run.id,
+                        kind: stringOrNull(candidate.kind),
+                        reviewStatus: stringOrNull(candidate.reviewStatus),
+                        label: payloadLabel(candidate.payload)
+                    });
+                }
+            }
+        }
+    }
+    catch (error) {
+        if (errorCode(error) !== 'ENOENT')
+            issues.push({ file: ONBOARDING_LEDGER_FILE, reason: errorMessage(error) });
+    }
+    const history = await readGraphCorrectionHistory(dataDir);
+    issues.push(...history.issues);
+    return {
+        extracted,
+        onboarding,
+        history: history.records,
+        corrections: new Map(history.records.map((record) => [record.id, record])),
+        issues
+    };
+}
+function resolveReference(edge, references) {
+    const sourceId = edge.provenance?.sourceId;
+    if (!sourceId)
+        return { status: 'none' };
+    const correction = references.corrections.get(sourceId);
+    if (correction) {
+        return { status: 'resolved', kind: 'graph_correction', file: GRAPH_CORRECTIONS_FILE, correctionId: correction.id, at: correction.at, reason: correction.reason };
+    }
+    const run = references.onboarding.get(sourceId);
+    if (run) {
+        return {
+            status: 'resolved',
+            kind: 'onboarding_run_candidate',
+            file: ONBOARDING_LEDGER_FILE,
+            runId: run.runId,
+            candidateId: sourceId,
+            candidateKind: run.kind,
+            reviewStatus: run.reviewStatus,
+            label: run.label
+        };
+    }
+    const extracted = references.extracted.get(sourceId);
+    if (extracted) {
+        return { status: 'resolved', kind: 'extracted_candidate', file: extracted.file, candidateId: sourceId, candidateKind: extracted.kind, label: extracted.label };
+    }
+    return { status: 'unresolved', sourceId };
+}
+function incidentEdges(graph, entityId, asOf, entities, references) {
+    return graph.edges.flatMap((edge) => {
+        const views = [];
+        if (edge.fromId === entityId)
+            views.push(edgeView(edge, 'outgoing', entities.get(edge.toId), asOf, references));
+        if (edge.toId === entityId)
+            views.push(edgeView(edge, 'incoming', entities.get(edge.fromId), asOf, references));
+        return views;
+    }).sort((left, right) => Number(right.active) - Number(left.active)
+        || left.relation.localeCompare(right.relation, 'en')
+        || left.counterpart.name.localeCompare(right.counterpart.name, 'ja')
+        || left.id.localeCompare(right.id, 'en'));
+}
+function edgeView(edge, direction, counterpart, asOf, references) {
+    if (!counterpart)
+        throw new GraphWebError('unavailable', 'graph_unavailable', `Relation ${edge.id} points to a missing entity`);
+    return {
+        id: edge.id,
+        relation: edge.relation,
+        meaning: getCanonicalRelation(edge.relation).meaning,
+        direction,
+        fromId: edge.fromId,
+        toId: edge.toId,
+        role: edge.role ?? null,
+        context: edge.context ?? null,
+        validFrom: edge.validFrom ?? null,
+        validTo: edge.validTo ?? null,
+        active: isActiveAt(edge, asOf),
+        provenance: {
+            sourceKind: edge.provenance?.sourceKind ?? null,
+            sourceId: edge.provenance?.sourceId ?? null,
+            evidenceHash: edge.provenance?.evidenceHash ?? null,
+            reference: resolveReference(edge, references)
+        },
+        counterpart: {
+            id: counterpart.id,
+            type: counterpart.type,
+            name: counterpart.name,
+            active: isActiveAt(counterpart, asOf),
+            digest: graphRecordDigest(counterpart)
+        },
+        digest: graphRecordDigest(edge)
+    };
+}
+function entityView(entity, asOf) {
+    return {
+        id: entity.id,
+        type: entity.type,
+        name: entity.name,
+        aliases: entity.aliases ?? [],
+        summary: entity.summary ?? null,
+        tags: entity.tags ?? [],
+        validFrom: entity.validFrom ?? null,
+        validTo: entity.validTo ?? null,
+        active: isActiveAt(entity, asOf),
+        digest: graphRecordDigest(entity),
+        ...(entity.type === 'project' ? { goal: metadataString(entity, 'goal'), status: metadataString(entity, 'status') } : {})
+    };
+}
+function projectView(project, asOf) {
+    return { ...entityView(project, asOf), type: 'project', goal: metadataString(project, 'goal'), status: metadataString(project, 'status') };
+}
+function historyFor(records, ids) {
+    return records.filter((record) => ids.has(record.target.id)).reverse();
+}
+function matchRank(entity, needle) {
+    if (!needle)
+        return 3;
+    if (normalize(entity.id) === needle)
+        return 0;
+    let best;
+    for (const value of [entity.name, ...(entity.aliases ?? [])]) {
+        const candidate = normalize(value);
+        const rank = candidate === needle ? 0 : candidate.startsWith(needle) ? 1 : candidate.includes(needle) ? 2 : undefined;
+        if (rank !== undefined && (best === undefined || rank < best))
+            best = rank;
+    }
+    return best;
+}
+function parseEntityType(value) {
+    if (value === undefined || value === '')
+        return null;
+    if (!ENTITY_KINDS.includes(value)) {
+        throw new GraphWebError('invalid', 'invalid_query', `type must be one of ${ENTITY_KINDS.join(', ')}`);
+    }
+    return value;
+}
+function resolveAsOf(options) {
+    if (options.asOf !== undefined && options.asOf !== '')
+        return parseAsOf(options.asOf);
+    return (options.now ?? new Date()).toISOString();
+}
+function parseAsOf(value) {
+    try {
+        isActiveAt({}, value);
+    }
+    catch {
+        throw new GraphWebError('invalid', 'invalid_query', 'as_of must be an RFC 3339 date-time such as 2026-09-30T00:00:00Z');
+    }
+    return value;
+}
+function entityIndex(graph) {
+    return new Map(graph.entities.map((entity) => [entity.id, entity]));
+}
+function isEntityActive(entity, asOf) {
+    return entity !== undefined && isActiveAt(entity, asOf);
+}
+function byActiveThenName(left, right) {
+    return Number(right.active) - Number(left.active) || left.name.localeCompare(right.name, 'ja') || left.id.localeCompare(right.id, 'en');
+}
+function byParticipation(left, right) {
+    const order = (edge) => edge.relation === 'accountable_for' ? 0 : 1;
+    return Number(right.active) - Number(left.active)
+        || order(left) - order(right)
+        || left.counterpart.name.localeCompare(right.counterpart.name, 'ja')
+        || left.id.localeCompare(right.id, 'en');
+}
+function metadataString(entity, key) {
+    const value = entity.metadata?.[key];
+    return typeof value === 'string' ? value : null;
+}
+function stringArray(value) {
+    return Array.isArray(value) ? value.filter((item) => typeof item === 'string') : [];
+}
+function payloadLabel(payload) {
+    if (!isRecord(payload))
+        return null;
+    for (const key of ['name', 'person', 'title', 'text']) {
+        if (typeof payload[key] === 'string' && payload[key])
+            return payload[key];
+    }
+    return null;
+}
+function normalize(value) {
+    return value.normalize('NFKC').replace(/\s+/gu, '').toLowerCase();
+}
+function stringOrNull(value) {
+    return typeof value === 'string' ? value : null;
+}
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+async function exists(path) {
+    try {
+        await access(path);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function errorCode(error) {
+    return typeof error === 'object' && error !== null && 'code' in error ? String(error.code) : undefined;
+}
+function errorMessage(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+function shellArg(value) {
+    return /^[A-Za-z0-9_./:@%+=,-]+$/u.test(value) ? value : JSON.stringify(value);
+}