@unson/brainbase-mcp 0.31.0 → 0.33.0

package/dist/graph-maintenance-engine.d.ts

@@ -0,0 +1,44 @@
+export type GraphRecord = Record<string, any>;
+export type GraphEntity = GraphRecord;
+export type GraphEdge = GraphRecord;
+export type GraphSnapshot = GraphRecord;
+export type GraphOperation = GraphRecord;
+export type GraphValidationIssue = {
+    category: string;
+    id?: unknown;
+};
+export type GraphValidation = {
+    valid: boolean;
+    counts: {
+        entities: number;
+        edges: number;
+        issues: number;
+        duplicates: number;
+        orphans: number;
+    };
+    issues: GraphValidationIssue[];
+};
+export type GraphPlanInput = GraphRecord;
+export type GraphPlan = {
+    dry_run: true;
+    project_code: any;
+    idempotency_key: any;
+    reason: string;
+    operations: GraphOperation[];
+    operation_count: number;
+    before_hash: string;
+    after_hash: string;
+    validation: GraphValidation;
+    before: GraphSnapshot;
+    after: GraphSnapshot;
+};
+export declare const GRAPH_MAINTENANCE_OPERATIONS: readonly string[];
+export declare const GRAPH_MAINTENANCE_MAX_OPERATIONS = 100;
+export declare function hashGraphSnapshot(snapshot: GraphSnapshot): string;
+export declare function findIntroducedGraphValidationIssues(beforeSnapshot: GraphSnapshot, afterSnapshot: GraphSnapshot): GraphValidationIssue[];
+export declare function applyGraphOperations(snapshot: GraphSnapshot, operations: GraphOperation[], { projectCode, humanGateReceipt }?: {
+    projectCode?: unknown;
+    humanGateReceipt?: unknown;
+}): GraphSnapshot;
+export declare function buildGraphPlan(snapshot: GraphSnapshot, input?: GraphPlanInput): GraphPlan;
+export declare function validateGraphSnapshot(snapshot: any): GraphValidation;

package/dist/graph-maintenance-engine.js

@@ -0,0 +1,804 @@
+// Moved from brainbase-unson server/services/graph-maintenance-engine.js without changing behavior.
+// Only type annotations were added; graph records stay open JSON objects as in the original.
+/* eslint-disable @typescript-eslint/no-explicit-any */
+import { createHash } from 'node:crypto';
+export const GRAPH_MAINTENANCE_OPERATIONS = Object.freeze([
+    'patch_entity', 'merge_entities', 'retire_entity', 'reactivate_project', 'move_scope', 'rehome_entity',
+    'upsert_edge', 'link_decision_subject', 'materialize_project_subject',
+    'link_decision_project_subject', 'retire_edge', 'normalize_alias',
+    'normalize_merged_lifecycle', 'create_entity', 'delete_entity', 'delete_edge',
+    'add_shared_membership'
+]);
+export const GRAPH_MAINTENANCE_MAX_OPERATIONS = 100;
+const SENSITIVITY_RANK = { internal: 0, restricted: 1, finance: 2, hr: 2, contract: 2 };
+const ROLE_RANK = { member: 1, gm: 2, ceo: 3 };
+const LIFECYCLE_STATUSES = new Set(['active', 'retired', 'superseded']);
+function canonicalize(value) {
+    if (Array.isArray(value))
+        return value.map(canonicalize);
+    if (!value || typeof value !== 'object')
+        return value;
+    return Object.fromEntries(Object.keys(value).sort().map((key) => [key, canonicalize(value[key])]));
+}
+function withoutHash(snapshot) {
+    const copy = structuredClone(snapshot);
+    delete copy.hash;
+    delete copy.snapshot_hash;
+    delete copy.snapshot_id;
+    delete copy.exported_at;
+    copy.entities = [...(copy.entities || [])].sort((a, b) => a.id.localeCompare(b.id));
+    if (Object.hasOwn(copy, 'external_entities')) {
+        copy.external_entities = [...(copy.external_entities || [])].sort((a, b) => a.id.localeCompare(b.id));
+    }
+    copy.edges = [...(copy.edges || [])].sort((a, b) => a.id.localeCompare(b.id));
+    return copy;
+}
+export function hashGraphSnapshot(snapshot) {
+    return `sha256:${createHash('sha256').update(JSON.stringify(canonicalize(withoutHash(snapshot)))).digest('hex')}`;
+}
+function requireVersion(record, operation) {
+    if (!Number.isInteger(operation.expected_version))
+        throw new Error('expected_version is required');
+    if (record.version !== operation.expected_version)
+        throw new Error('expected_version conflict');
+}
+function assertSensitivity(current, next) {
+    if (!(current in SENSITIVITY_RANK))
+        throw new Error('Invalid sensitivity');
+    if (next === undefined)
+        return;
+    if (!(next in SENSITIVITY_RANK))
+        throw new Error('Invalid sensitivity');
+    if (SENSITIVITY_RANK[next] < SENSITIVITY_RANK[current])
+        throw new Error('sensitivity cannot be lowered');
+}
+function assertRoleMinimum(current, next) {
+    if (!(current in ROLE_RANK))
+        throw new Error('Invalid role_min');
+    if (next === undefined)
+        return;
+    if (!(next in ROLE_RANK))
+        throw new Error('Invalid role_min');
+    if (ROLE_RANK[next] < ROLE_RANK[current])
+        throw new Error('role_min cannot be lowered');
+}
+function assertAccessMetadata(roleMin, sensitivity) {
+    if (!(roleMin in ROLE_RANK))
+        throw new Error('Invalid role_min');
+    if (!(sensitivity in SENSITIVITY_RANK))
+        throw new Error('Invalid sensitivity');
+    if (SENSITIVITY_RANK[sensitivity] >= SENSITIVITY_RANK.finance && roleMin === 'member') {
+        throw new Error('Sensitive data requires role_min gm or ceo');
+    }
+}
+function validationError(validation, prefix = 'Graph snapshot is invalid') {
+    return new Error(`${prefix}: ${validation.issues.map((item) => item.category).join(',')}`);
+}
+function validationIssueKey(issue) {
+    return JSON.stringify(canonicalize(issue));
+}
+function introducedValidationIssues(before, after) {
+    const remaining = new Map();
+    for (const issue of before.issues) {
+        const key = validationIssueKey(issue);
+        remaining.set(key, (remaining.get(key) || 0) + 1);
+    }
+    return after.issues.filter((issue) => {
+        const key = validationIssueKey(issue);
+        const count = remaining.get(key) || 0;
+        if (count === 0)
+            return true;
+        remaining.set(key, count - 1);
+        return false;
+    });
+}
+export function findIntroducedGraphValidationIssues(beforeSnapshot, afterSnapshot) {
+    return introducedValidationIssues(validateGraphSnapshot(beforeSnapshot), validateGraphSnapshot(afterSnapshot));
+}
+function findEntity(state, id) {
+    const entity = (state.entities || []).find((item) => item.id === id);
+    if (!entity)
+        throw new Error(`Unknown entity: ${id}`);
+    return entity;
+}
+function findAnyEntity(state, id) {
+    const entity = [...(state.entities || []), ...(state.external_entities || [])].find((item) => item.id === id);
+    if (!entity)
+        throw new Error(`Unknown entity: ${id}`);
+    return entity;
+}
+function findAnyEntityOrNull(state, id) {
+    return [...(state.entities || []), ...(state.external_entities || [])].find((item) => item.id === id) || null;
+}
+function assertProjectCatalogProvenance(project) {
+    const catalogProjectId = project.payload?.catalog_project_id;
+    if (catalogProjectId !== project.id) {
+        throw new Error('Project subject catalog_project_id must match Graph Entity ID');
+    }
+    const catalogVersion = project.payload?.catalog_version;
+    if (!Number.isInteger(catalogVersion) || catalogVersion < 1) {
+        throw new Error('Project subject catalog_version must be a positive integer');
+    }
+    const expectedSourceRef = `project-catalog:${catalogProjectId}@${catalogVersion}`;
+    if (project.payload?.source_ref !== expectedSourceRef) {
+        throw new Error('Project subject source_ref must match Catalog Project identity and version');
+    }
+    if (!String(project.payload?.name || '').trim()) {
+        throw new Error('Project subject Catalog name is required');
+    }
+}
+function isActiveDecision(entity) {
+    return entity.entity_type === 'decision'
+        && entity.lifecycle_status === 'active'
+        && !['retired', 'superseded'].includes(String(entity.payload?.status || '').toLowerCase());
+}
+function findEdge(state, operation) {
+    const edge = operation.edge_id
+        ? state.edges.find((item) => item.id === operation.edge_id)
+        : state.edges.find((item) => item.from_id === operation.from_id && item.to_id === operation.to_id && item.rel_type === operation.rel_type);
+    if (!edge)
+        throw new Error('Unknown edge');
+    return edge;
+}
+const SHARED_MEMBERSHIP_DATE = /^\d{4}-\d{2}-\d{2}$/;
+/**
+ * Add one person -> project member_of edge for a shared Person that lives
+ * outside this project. The Person and every existing edge stay unchanged;
+ * an existing active membership makes the operation a no-op.
+ */
+function addSharedMembership(state, operation, humanGateReceipt) {
+    const decision = findEntity(state, operation.decision_id);
+    const project = findEntity(state, operation.target_project_entity_id);
+    const person = (state.external_entities || []).find((item) => item.id === operation.subject_entity_id);
+    if (!person)
+        throw new Error('Shared person endpoint is required');
+    requireVersion(decision, { expected_version: operation.decision_expected_version });
+    requireVersion(person, { expected_version: operation.subject_expected_version });
+    requireVersion(project, { expected_version: operation.target_project_expected_version });
+    if (!isActiveDecision(decision) || decision.project_code !== state.project_code) {
+        throw new Error('active Decision in the target project is required');
+    }
+    if (person.entity_type !== 'person' || person.lifecycle_status !== 'active'
+        || !['shared_person', 'same_organization'].includes(person.reference_scope)) {
+        throw new Error('active shared Person is required');
+    }
+    if (project.entity_type !== 'project' || project.lifecycle_status !== 'active'
+        || project.project_code !== state.project_code) {
+        throw new Error('active Project entity in the target project is required');
+    }
+    if (operation.target_project_code !== state.project_code)
+        throw new Error('target_project_code must be the plan project');
+    const receipt = operation.human_gate_receipt || humanGateReceipt;
+    if (!String(receipt || '').trim())
+        throw new Error('human_gate_receipt is required for shared membership');
+    const basis = String(operation.basis || '').trim();
+    if (!basis || basis.length > 1000)
+        throw new Error('basis is required (at most 1000 characters)');
+    const confirmedAt = String(operation.confirmed_at || '');
+    if (!SHARED_MEMBERSHIP_DATE.test(confirmedAt) || Number.isNaN(Date.parse(`${confirmedAt}T00:00:00Z`))) {
+        throw new Error('confirmed_at must be a YYYY-MM-DD date');
+    }
+    const existing = state.edges.find((edge) => edge.from_id === person.id && edge.to_id === project.id
+        && edge.rel_type === 'member_of');
+    if (existing?.lifecycle_status === 'active')
+        return;
+    if (existing)
+        throw new Error('A retired membership exists; reactivate it with upsert_edge');
+    if (operation.expected_version !== 0)
+        throw new Error('expected_version conflict');
+    if (!String(operation.edge_id || '').trim())
+        throw new Error('edge_id is required');
+    if (state.edges.some((edge) => edge.id === operation.edge_id))
+        throw new Error('edge id conflict');
+    state.edges.push({
+        id: operation.edge_id,
+        from_id: person.id,
+        to_id: project.id,
+        rel_type: 'member_of',
+        project_code: state.project_code,
+        payload: {
+            source: 'graph_maintenance:add_shared_membership',
+            source_graph_scope: 'shared_person',
+            basis,
+            confirmed_at: confirmedAt,
+            decision_id: decision.id,
+            human_gate_receipt: receipt
+        },
+        role_min: 'member',
+        sensitivity: 'internal',
+        lifecycle_status: 'active',
+        version: 1
+    });
+}
+export function applyGraphOperations(snapshot, operations, { projectCode, humanGateReceipt } = {}) {
+    const initialValidation = validateGraphSnapshot(snapshot);
+    const state = withoutHash(snapshot);
+    if (state.project_code !== projectCode)
+        throw new Error('project scope mismatch');
+    for (const operation of operations) {
+        if (!GRAPH_MAINTENANCE_OPERATIONS.includes(operation.operation))
+            throw new Error(`Unknown graph operation: ${operation.operation}`);
+        if (operation.operation === 'create_entity') {
+            if (operation.expected_version !== 0)
+                throw new Error('expected_version conflict');
+            const entityId = String(operation.entity_id || '').trim();
+            const entityType = String(operation.entity_type || '').trim();
+            if (!entityId)
+                throw new Error('entity_id is required');
+            if (!entityType)
+                throw new Error('entity_type is required');
+            // Project subjects carry Project Catalog provenance and are created
+            // only through materialize_project_subject.
+            if (entityType === 'project')
+                throw new Error('Project entities must use materialize_project_subject');
+            if (operation.payload !== undefined
+                && (!operation.payload || typeof operation.payload !== 'object' || Array.isArray(operation.payload))) {
+                throw new Error('payload must be an object');
+            }
+            if (findAnyEntityOrNull(state, entityId))
+                throw new Error('entity id conflict');
+            const roleMin = operation.role_min || 'member';
+            const sensitivity = operation.sensitivity || 'internal';
+            assertAccessMetadata(roleMin, sensitivity);
+            state.entities.push({
+                id: entityId,
+                entity_type: entityType,
+                project_code: state.project_code,
+                payload: structuredClone(operation.payload || {}),
+                role_min: roleMin,
+                sensitivity,
+                lifecycle_status: 'active',
+                version: 1
+            });
+        }
+        else if (operation.operation === 'delete_entity') {
+            // Physical removal. retire_entity remains the logical lifecycle change.
+            const entity = findEntity(state, operation.entity_id);
+            if (entity.entity_type === 'project')
+                throw new Error('Project entities cannot be physically deleted; use retire_entity');
+            requireVersion(entity, operation);
+            if (isActiveDecision(entity) && !(operation.human_gate_receipt || humanGateReceipt)) {
+                throw new Error('human_gate_receipt is required for Active Decision');
+            }
+            if (state.edges.some((edge) => edge.from_id === entity.id || edge.to_id === entity.id)) {
+                throw new Error('entity still has edges; delete them in the same plan first');
+            }
+            state.entities = state.entities.filter((item) => item.id !== entity.id);
+        }
+        else if (operation.operation === 'delete_edge') {
+            const edge = findEdge(state, operation);
+            requireVersion(edge, operation);
+            state.edges = state.edges.filter((item) => item.id !== edge.id);
+        }
+        else if (operation.operation === 'patch_entity') {
+            const entity = findEntity(state, operation.entity_id);
+            requireVersion(entity, operation);
+            assertSensitivity(entity.sensitivity, operation.sensitivity);
+            assertRoleMinimum(entity.role_min, operation.role_min);
+            entity.payload = { ...entity.payload, ...(operation.patch || {}) };
+            if (operation.role_min !== undefined)
+                entity.role_min = operation.role_min;
+            if (operation.sensitivity !== undefined)
+                entity.sensitivity = operation.sensitivity;
+            assertAccessMetadata(entity.role_min, entity.sensitivity);
+            entity.version += 1;
+        }
+        else if (operation.operation === 'retire_entity') {
+            const entity = findEntity(state, operation.entity_id);
+            requireVersion(entity, operation);
+            if (isActiveDecision(entity) && !(operation.human_gate_receipt || humanGateReceipt))
+                throw new Error('human_gate_receipt is required for Active Decision');
+            entity.lifecycle_status = 'retired';
+            entity.version += 1;
+        }
+        else if (operation.operation === 'reactivate_project') {
+            const entity = findEntity(state, operation.entity_id);
+            requireVersion(entity, operation);
+            if (entity.entity_type !== 'project')
+                throw new Error('reactivate_project requires a Project entity');
+            if (entity.lifecycle_status !== 'retired')
+                throw new Error('reactivate_project requires a retired Project');
+            entity.lifecycle_status = 'active';
+            entity.version += 1;
+        }
+        else if (operation.operation === 'move_scope') {
+            const entity = findEntity(state, operation.entity_id);
+            requireVersion(entity, operation);
+            if (!operation.target_project_code)
+                throw new Error('target_project_code is required');
+            entity.project_code = operation.target_project_code;
+            entity.version += 1;
+            for (const edge of state.edges.filter((item) => item.from_id === entity.id || item.to_id === entity.id)) {
+                edge.project_code = operation.target_project_code;
+                edge.version += 1;
+            }
+        }
+        else if (operation.operation === 'rehome_entity') {
+            const entity = findEntity(state, operation.entity_id);
+            requireVersion(entity, operation);
+            if (!String(operation.target_project_code || '').trim())
+                throw new Error('target_project_code is required');
+            if (!String(operation.target_project_entity_id || '').trim())
+                throw new Error('target_project_entity_id is required');
+            const targetProject = findEntity(state, operation.target_project_entity_id);
+            requireVersion(targetProject, { expected_version: operation.target_project_expected_version });
+            if (targetProject.entity_type !== 'project')
+                throw new Error('target Project entity_type is required');
+            if (targetProject.lifecycle_status !== 'active')
+                throw new Error('target Project must be active');
+            if (targetProject.project_code !== operation.target_project_code)
+                throw new Error('target Project scope mismatch');
+            if (!String(operation.membership_edge_id || '').trim())
+                throw new Error('membership_edge_id is required');
+            const membership = findEdge(state, { edge_id: operation.membership_edge_id });
+            requireVersion(membership, { expected_version: operation.membership_expected_version });
+            if (membership.rel_type !== 'belongs_to_project'
+                || membership.from_id !== entity.id
+                || membership.lifecycle_status !== 'active') {
+                throw new Error('active belongs_to_project membership is required');
+            }
+            if (membership.project_code !== entity.project_code)
+                throw new Error('membership source scope mismatch');
+            if (operation.new_membership_expected_version !== 0)
+                throw new Error('expected_version conflict');
+            if (!String(operation.new_membership_edge_id || '').trim())
+                throw new Error('new_membership_edge_id is required');
+            if (state.edges.some((edge) => edge.id === operation.new_membership_edge_id))
+                throw new Error('edge id conflict');
+            membership.lifecycle_status = 'retired';
+            membership.version += 1;
+            entity.project_code = operation.target_project_code;
+            entity.version += 1;
+            state.edges.push({
+                ...structuredClone(membership),
+                id: operation.new_membership_edge_id,
+                from_id: entity.id,
+                to_id: targetProject.id,
+                project_code: operation.target_project_code,
+                lifecycle_status: 'active',
+                version: 1
+            });
+        }
+        else if (operation.operation === 'merge_entities') {
+            const source = findEntity(state, operation.source_entity_id);
+            const target = findEntity(state, operation.target_entity_id);
+            requireVersion(source, { expected_version: operation.source_expected_version });
+            requireVersion(target, { expected_version: operation.target_expected_version });
+            if (source.project_code !== target.project_code)
+                throw new Error('project scope mismatch');
+            assertSensitivity(source.sensitivity, target.sensitivity);
+            assertRoleMinimum(source.role_min, target.role_min);
+            target.payload = { ...source.payload, ...target.payload, aliases: [...new Set([...(target.payload?.aliases || []), source.id, ...(source.payload?.aliases || [])])] };
+            target.version += 1;
+            source.lifecycle_status = 'superseded';
+            source.payload = { ...source.payload, canonical_entity_id: target.id };
+            source.version += 1;
+            for (const edge of state.edges) {
+                let changed = false;
+                if (edge.from_id === source.id) {
+                    edge.from_id = target.id;
+                    changed = true;
+                }
+                if (edge.to_id === source.id) {
+                    edge.to_id = target.id;
+                    changed = true;
+                }
+                if (changed)
+                    edge.version += 1;
+            }
+        }
+        else if (operation.operation === 'normalize_merged_lifecycle') {
+            const source = findEntity(state, operation.entity_id);
+            const target = findEntity(state, operation.target_entity_id);
+            requireVersion(source, operation);
+            requireVersion(target, { expected_version: operation.target_expected_version });
+            if (source.id === target.id)
+                throw new Error('source and target must differ');
+            if (source.project_code !== target.project_code)
+                throw new Error('project scope mismatch');
+            if (source.entity_type !== target.entity_type)
+                throw new Error('entity_type mismatch');
+            if (source.lifecycle_status !== 'merged')
+                throw new Error('source lifecycle_status must be merged');
+            if (source.payload?.canonical_entity_id !== target.id)
+                throw new Error('canonical_entity_id mismatch');
+            if (target.lifecycle_status !== 'active')
+                throw new Error('target must be active');
+            if (state.edges.some((edge) => edge.lifecycle_status === 'active'
+                && (edge.from_id === source.id || edge.to_id === source.id))) {
+                throw new Error('source still has active edges');
+            }
+            source.lifecycle_status = 'superseded';
+            source.version += 1;
+        }
+        else if (operation.operation === 'upsert_edge') {
+            const externalIds = new Set((state.external_entities || []).map((entity) => entity.id));
+            const toEntity = findAnyEntity(state, operation.to_id);
+            const localFrom = (state.entities || []).find((item) => item.id === operation.from_id) || null;
+            const externalFrom = localFrom ? null : findAnyEntityOrNull(state, operation.from_id);
+            // The accountable person of a tool: a same-organization person outside this project.
+            const sameOrganizationToolAccountable = operation.rel_type === 'accountable_for'
+                && externalFrom?.entity_type === 'person'
+                && externalFrom.lifecycle_status === 'active'
+                && externalFrom.reference_scope === 'same_organization'
+                && externalIds.has(externalFrom.id)
+                && !externalIds.has(toEntity.id)
+                && toEntity.entity_type === 'app'
+                && toEntity.lifecycle_status === 'active';
+            if (!localFrom && !sameOrganizationToolAccountable)
+                throw new Error(`Unknown entity: ${operation.from_id}`);
+            const fromEntity = (localFrom || externalFrom);
+            // A project of this scope using a same-organization tool of another project.
+            const sameOrganizationProjectUsesApp = operation.rel_type === 'uses_app'
+                && Boolean(localFrom)
+                && fromEntity.entity_type === 'project'
+                && fromEntity.lifecycle_status === 'active'
+                && toEntity.entity_type === 'app'
+                && toEntity.lifecycle_status === 'active'
+                && toEntity.reference_scope === 'same_organization'
+                && externalIds.has(toEntity.id);
+            const sameOrganizationAppOwner = operation.rel_type === 'owned_by'
+                && fromEntity.entity_type === 'app'
+                && fromEntity.lifecycle_status === 'active'
+                && toEntity.entity_type === 'org'
+                && toEntity.lifecycle_status === 'active'
+                && toEntity.reference_scope === 'same_organization'
+                && (state.external_entities || []).some((entity) => entity.id === toEntity.id);
+            const sameOrganizationDecisionOwner = operation.rel_type === 'owned_by'
+                && isActiveDecision(fromEntity)
+                && toEntity.entity_type === 'person'
+                && toEntity.lifecycle_status === 'active'
+                && toEntity.reference_scope === 'same_organization'
+                && (state.external_entities || []).some((entity) => entity.id === toEntity.id);
+            if (sameOrganizationDecisionOwner && operation.decision_id !== fromEntity.id) {
+                // Bind this relationship mutation to the existing plan-level Human Gate.
+                throw new Error('decision_id must match the Decision owner source');
+            }
+            if (fromEntity.project_code !== toEntity.project_code && !sameOrganizationAppOwner && !sameOrganizationDecisionOwner
+                && !sameOrganizationToolAccountable && !sameOrganizationProjectUsesApp) {
+                throw new Error('edge endpoint project scope mismatch');
+            }
+            if (!String(operation.rel_type || '').trim())
+                throw new Error('rel_type is required');
+            const existing = state.edges.find((item) => item.from_id === operation.from_id && item.to_id === operation.to_id && item.rel_type === operation.rel_type);
+            const edgeById = operation.edge_id ? state.edges.find((item) => item.id === operation.edge_id) : null;
+            if (existing && operation.edge_id && existing.id !== operation.edge_id)
+                throw new Error('edge_id does not match existing edge');
+            if (!existing && edgeById)
+                throw new Error('edge id conflict');
+            if (existing) {
+                requireVersion(existing, operation);
+                assertSensitivity(existing.sensitivity, operation.sensitivity);
+                assertRoleMinimum(existing.role_min, operation.role_min);
+                existing.payload = { ...existing.payload, ...(operation.payload || {}) };
+                if (operation.role_min !== undefined)
+                    existing.role_min = operation.role_min;
+                if (operation.sensitivity !== undefined)
+                    existing.sensitivity = operation.sensitivity;
+                assertAccessMetadata(existing.role_min, existing.sensitivity);
+                existing.lifecycle_status = 'active';
+                existing.version += 1;
+            }
+            else {
+                if (operation.expected_version !== 0)
+                    throw new Error('expected_version conflict');
+                if (!operation.edge_id)
+                    throw new Error('edge_id is required');
+                const roleMin = operation.role_min || 'member';
+                const sensitivity = operation.sensitivity || 'internal';
+                assertAccessMetadata(roleMin, sensitivity);
+                state.edges.push({
+                    id: operation.edge_id,
+                    from_id: operation.from_id, to_id: operation.to_id, rel_type: operation.rel_type,
+                    // The accountable person lives in another project; the edge belongs to the tool's project.
+                    project_code: sameOrganizationToolAccountable ? toEntity.project_code : fromEntity.project_code,
+                    payload: operation.payload || {}, role_min: roleMin,
+                    sensitivity, lifecycle_status: 'active', version: 1
+                });
+            }
+        }
+        else if (operation.operation === 'materialize_project_subject') {
+            if (operation.expected_version !== 0)
+                throw new Error('expected_version conflict');
+            if (!String(operation.entity_id || '').trim())
+                throw new Error('entity_id is required');
+            if (operation.catalog_project_id !== operation.entity_id) {
+                throw new Error('Catalog Project ID must match Graph Entity ID');
+            }
+            if (!Number.isInteger(operation.catalog_version) || operation.catalog_version < 1) {
+                throw new Error('catalog_version must be a positive integer');
+            }
+            if (!String(operation.name || '').trim())
+                throw new Error('name is required');
+            const expectedSourceRef = `project-catalog:${operation.catalog_project_id}@${operation.catalog_version}`;
+            if (operation.source_ref !== expectedSourceRef)
+                throw new Error('source_ref must match Catalog Project identity and version');
+            if (findAnyEntityOrNull(state, operation.entity_id))
+                throw new Error('entity id conflict');
+            state.entities.push({
+                id: operation.entity_id,
+                entity_type: 'project',
+                project_code: state.project_code,
+                payload: {
+                    name: operation.name,
+                    catalog_project_id: operation.catalog_project_id,
+                    catalog_version: operation.catalog_version,
+                    source_ref: operation.source_ref,
+                    ...(operation.kind ? { kind: operation.kind } : {}),
+                    ...(operation.organization_entity_id
+                        ? { organization_entity_id: operation.organization_entity_id } : {}),
+                    ...(operation.owner_person_id ? { owner_person_id: operation.owner_person_id } : {})
+                },
+                role_min: 'member',
+                sensitivity: 'internal',
+                lifecycle_status: 'active',
+                version: 1
+            });
+        }
+        else if (operation.operation === 'link_decision_project_subject') {
+            const decision = findEntity(state, operation.decision_id);
+            const subject = findEntity(state, operation.subject_entity_id);
+            requireVersion(decision, { expected_version: operation.decision_expected_version });
+            requireVersion(subject, { expected_version: operation.subject_expected_version });
+            if (decision.entity_type !== 'decision' || decision.lifecycle_status !== 'active')
+                throw new Error('active Decision source is required');
+            if (subject.entity_type !== 'project' || subject.lifecycle_status !== 'active')
+                throw new Error('active Project subject is required');
+            assertProjectCatalogProvenance(subject);
+            if (decision.project_code !== state.project_code || subject.project_code !== state.project_code) {
+                throw new Error('Decision project subject scope mismatch');
+            }
+            if (!(operation.human_gate_receipt || humanGateReceipt)) {
+                throw new Error('human_gate_receipt is required for Decision project subject link');
+            }
+            if (operation.expected_version !== 0)
+                throw new Error('expected_version conflict');
+            if (!String(operation.edge_id || '').trim())
+                throw new Error('edge_id is required');
+            if (state.edges.some((edge) => edge.id === operation.edge_id))
+                throw new Error('edge id conflict');
+            if (state.edges.some((edge) => edge.from_id === decision.id && edge.to_id === subject.id && edge.rel_type === 'governs')) {
+                throw new Error('Decision project subject edge already exists');
+            }
+            state.edges.push({
+                id: operation.edge_id,
+                from_id: decision.id,
+                to_id: subject.id,
+                rel_type: 'governs',
+                project_code: decision.project_code,
+                payload: { catalog_project_id: subject.payload.catalog_project_id },
+                role_min: 'ceo',
+                sensitivity: 'restricted',
+                lifecycle_status: 'active',
+                version: 1
+            });
+        }
+        else if (operation.operation === 'link_decision_subject') {
+            const decision = findEntity(state, operation.decision_id);
+            const subject = findAnyEntity(state, operation.subject_entity_id);
+            requireVersion(decision, { expected_version: operation.decision_expected_version });
+            requireVersion(subject, { expected_version: operation.subject_expected_version });
+            if (decision.entity_type !== 'decision' || decision.lifecycle_status !== 'active')
+                throw new Error('active Decision source is required');
+            if (subject.entity_type !== 'product' || subject.lifecycle_status !== 'active')
+                throw new Error('active Product subject is required');
+            if (decision.project_code !== state.project_code)
+                throw new Error('Decision source scope mismatch');
+            if (!String(operation.target_project_code || '').trim() || subject.project_code !== operation.target_project_code) {
+                throw new Error('Product target scope mismatch');
+            }
+            if (decision.project_code === subject.project_code)
+                throw new Error('link_decision_subject requires cross-project endpoints');
+            if (!(operation.human_gate_receipt || humanGateReceipt))
+                throw new Error('human_gate_receipt is required for Decision subject link');
+            if (operation.expected_version !== 0)
+                throw new Error('expected_version conflict');
+            if (!String(operation.edge_id || '').trim())
+                throw new Error('edge_id is required');
+            if (state.edges.some((edge) => edge.id === operation.edge_id))
+                throw new Error('edge id conflict');
+            if (state.edges.some((edge) => edge.from_id === decision.id && edge.to_id === subject.id && edge.rel_type === 'governs')) {
+                throw new Error('Decision subject edge already exists');
+            }
+            state.edges.push({
+                id: operation.edge_id,
+                from_id: decision.id,
+                to_id: subject.id,
+                rel_type: 'governs',
+                project_code: decision.project_code,
+                payload: { ...(operation.payload || {}), target_project_code: subject.project_code, cross_tenant: true },
+                role_min: 'ceo',
+                sensitivity: 'restricted',
+                lifecycle_status: 'active',
+                version: 1
+            });
+        }
+        else if (operation.operation === 'add_shared_membership') {
+            addSharedMembership(state, operation, humanGateReceipt);
+        }
+        else if (operation.operation === 'retire_edge') {
+            const edge = findEdge(state, operation);
+            requireVersion(edge, operation);
+            edge.lifecycle_status = 'retired';
+            edge.version += 1;
+        }
+        else if (operation.operation === 'normalize_alias') {
+            const entity = findEntity(state, operation.entity_id);
+            requireVersion(entity, operation);
+            const aliases = Array.isArray(operation.aliases) ? operation.aliases : entity.payload?.aliases || [];
+            entity.payload = { ...entity.payload, aliases: [...new Set(aliases.map((item) => String(item).trim()).filter(Boolean))].sort() };
+            entity.version += 1;
+        }
+    }
+    const finalValidation = validateGraphSnapshot(state);
+    const introducedIssues = introducedValidationIssues(initialValidation, finalValidation);
+    if (introducedIssues.length) {
+        throw validationError({ issues: introducedIssues }, 'Graph operations introduced invalid state');
+    }
+    state.hash = hashGraphSnapshot(state);
+    return state;
+}
+export function buildGraphPlan(snapshot, input = {}) {
+    if (!String(input.reason || '').trim())
+        throw new Error('reason is required');
+    if (!String(input.idempotency_key || '').trim())
+        throw new Error('idempotency_key is required');
+    if (snapshot.project_code !== input.project_code)
+        throw new Error('project scope mismatch');
+    if (snapshot.hash && snapshot.hash !== hashGraphSnapshot(snapshot))
+        throw new Error('snapshot hash mismatch');
+    const operations = Array.isArray(input.operations) ? input.operations : [];
+    const max = Math.min(Number(input.max_operations) || GRAPH_MAINTENANCE_MAX_OPERATIONS, GRAPH_MAINTENANCE_MAX_OPERATIONS);
+    if (operations.length > max)
+        throw new Error('bulk operation limit exceeded');
+    const before = structuredClone(snapshot);
+    before.hash = hashGraphSnapshot(before);
+    const after = applyGraphOperations(before, operations, { projectCode: input.project_code, humanGateReceipt: input.human_gate_receipt });
+    const validation = validateGraphSnapshot(after);
+    return {
+        dry_run: true,
+        project_code: input.project_code,
+        idempotency_key: input.idempotency_key,
+        reason: input.reason.trim(),
+        operations,
+        operation_count: operations.length,
+        before_hash: before.hash,
+        after_hash: after.hash,
+        validation,
+        before,
+        after
+    };
+}
+export function validateGraphSnapshot(snapshot) {
+    const issues = [];
+    if (!snapshot || typeof snapshot !== 'object' || Array.isArray(snapshot)) {
+        return { valid: false, counts: { entities: 0, edges: 0, issues: 1, duplicates: 0, orphans: 0 }, issues: [{ category: 'snapshot' }] };
+    }
+    if (!String(snapshot.project_code || '').trim())
+        issues.push({ category: 'project_scope' });
+    if (!Array.isArray(snapshot.entities))
+        issues.push({ category: 'entities' });
+    if (!Array.isArray(snapshot.edges))
+        issues.push({ category: 'edges' });
+    const entityIds = new Set();
+    const entitiesById = new Map();
+    const externalEntityIds = new Set((Array.isArray(snapshot.external_entities) ? snapshot.external_entities : [])
+        .map((entity) => entity?.id)
+        .filter(Boolean));
+    const allEntities = [
+        ...(Array.isArray(snapshot.entities) ? snapshot.entities : []),
+        ...(Array.isArray(snapshot.external_entities) ? snapshot.external_entities : [])
+    ];
+    for (const entity of allEntities) {
+        if (!entity || typeof entity !== 'object' || Array.isArray(entity)) {
+            issues.push({ category: 'entity' });
+            continue;
+        }
+        if (!String(entity.id || '').trim())
+            issues.push({ category: 'entity_id', id: entity.id });
+        if (entityIds.has(entity.id))
+            issues.push({ category: 'duplicate_entity', id: entity.id });
+        entityIds.add(entity.id);
+        entitiesById.set(entity.id, entity);
+        if (!Number.isInteger(entity.version) || entity.version < 1)
+            issues.push({ category: 'version', id: entity.id });
+        if (!String(entity.entity_type || '').trim())
+            issues.push({ category: 'entity_type', id: entity.id });
+        if (!String(entity.project_code || '').trim())
+            issues.push({ category: 'project_scope', id: entity.id });
+        if (!(entity.role_min in ROLE_RANK))
+            issues.push({ category: 'role_min', id: entity.id });
+        if (!(entity.sensitivity in SENSITIVITY_RANK))
+            issues.push({ category: 'sensitivity', id: entity.id });
+        if (!LIFECYCLE_STATUSES.has(entity.lifecycle_status))
+            issues.push({ category: 'lifecycle', id: entity.id });
+        // Cross-tenant endpoints are deliberately represented by metadata only.
+        // Requiring payload here would either invalidate every safe plan or copy
+        // target-tenant business data into the source-tenant receipt.
+        if (!externalEntityIds.has(entity.id)
+            && (!entity.payload || typeof entity.payload !== 'object' || Array.isArray(entity.payload))) {
+            issues.push({ category: 'payload', id: entity.id });
+        }
+        if (SENSITIVITY_RANK[entity.sensitivity] >= SENSITIVITY_RANK.finance && entity.role_min === 'member') {
+            issues.push({ category: 'sensitivity_role', id: entity.id });
+        }
+    }
+    const edgeKeys = new Set();
+    const edgeIds = new Set();
+    for (const edge of Array.isArray(snapshot.edges) ? snapshot.edges : []) {
+        if (!edge || typeof edge !== 'object' || Array.isArray(edge)) {
+            issues.push({ category: 'edge' });
+            continue;
+        }
+        if (!String(edge.id || '').trim())
+            issues.push({ category: 'edge_id', id: edge.id });
+        if (edgeIds.has(edge.id))
+            issues.push({ category: 'duplicate_edge_id', id: edge.id });
+        edgeIds.add(edge.id);
+        if (!Number.isInteger(edge.version) || edge.version < 1)
+            issues.push({ category: 'edge_version', id: edge.id });
+        if (!String(edge.rel_type || '').trim())
+            issues.push({ category: 'rel_type', id: edge.id });
+        if (!String(edge.project_code || '').trim())
+            issues.push({ category: 'project_scope', id: edge.id });
+        if (!(edge.role_min in ROLE_RANK))
+            issues.push({ category: 'role_min', id: edge.id });
+        if (!(edge.sensitivity in SENSITIVITY_RANK))
+            issues.push({ category: 'sensitivity', id: edge.id });
+        if (!LIFECYCLE_STATUSES.has(edge.lifecycle_status))
+            issues.push({ category: 'lifecycle', id: edge.id });
+        if (!edge.payload || typeof edge.payload !== 'object' || Array.isArray(edge.payload))
+            issues.push({ category: 'payload', id: edge.id });
+        if (SENSITIVITY_RANK[edge.sensitivity] >= SENSITIVITY_RANK.finance && edge.role_min === 'member') {
+            issues.push({ category: 'sensitivity_role', id: edge.id });
+        }
+        if (!entityIds.has(edge.from_id) || !entityIds.has(edge.to_id))
+            issues.push({ category: 'orphan', id: edge.id });
+        if (edge.rel_type === 'belongs_to_project' && edge.lifecycle_status === 'active') {
+            const source = entitiesById.get(edge.from_id);
+            const target = entitiesById.get(edge.to_id);
+            if (source && target && (target.entity_type !== 'project'
+                || source.project_code !== edge.project_code
+                || target.project_code !== edge.project_code)) {
+                issues.push({ category: 'membership_scope', id: edge.id });
+            }
+        }
+        const source = entitiesById.get(edge.from_id);
+        const target = entitiesById.get(edge.to_id);
+        const targetIsCrossTenant = externalEntityIds.has(target?.id)
+            && target.reference_scope !== 'same_organization';
+        if (source && target
+            && (targetIsCrossTenant || edge.payload?.cross_tenant === true)
+            && source.project_code !== target.project_code) {
+            const canonicalCrossTenant = edge.rel_type === 'governs'
+                && edge.project_code === source.project_code
+                && edge.payload?.cross_tenant === true
+                && edge.payload?.target_project_code === target.project_code
+                && edge.role_min === 'ceo'
+                && edge.sensitivity === 'restricted';
+            if (!canonicalCrossTenant
+                || source.entity_type !== 'decision'
+                || source.lifecycle_status !== 'active'
+                || target.entity_type !== 'product'
+                || target.reference_scope === 'same_organization'
+                || target.lifecycle_status !== 'active') {
+                issues.push({ category: 'cross_tenant_edge', id: edge.id });
+            }
+        }
+        const key = `${edge.from_id}\u0000${edge.to_id}\u0000${edge.rel_type}`;
+        if (edgeKeys.has(key))
+            issues.push({ category: 'duplicate_edge', id: edge.id });
+        edgeKeys.add(key);
+    }
+    return {
+        valid: issues.length === 0,
+        counts: {
+            entities: Array.isArray(snapshot.entities) ? snapshot.entities.length : 0,
+            edges: Array.isArray(snapshot.edges) ? snapshot.edges.length : 0,
+            issues: issues.length,
+            duplicates: issues.filter((item) => item.category.startsWith('duplicate')).length,
+            orphans: issues.filter((item) => item.category === 'orphan').length
+        },
+        issues
+    };
+}

package/dist/memory-scope-policy.d.ts

@@ -0,0 +1,43 @@
+export type MemoryRecordInput = Record<string, any> | null | undefined;
+export type MemoryAccessContextInput = Record<string, any>;
+export type MemoryAccessContext = {
+    person_id: string | null;
+    workspace: string | null;
+    channel_id: string | null;
+    session_id: string | null;
+    roles: string[];
+    role_rank: number;
+    project_codes: string[];
+    clearance: string[];
+};
+export type NormalizedMemoryRecord = {
+    id: string | null;
+    visibility: string;
+    owner_person_id: string | null;
+    workspace: string | null;
+    channel_id: string | null;
+    project_code: string | null;
+    role_min: string;
+    sensitivity: string;
+};
+export type MemoryScopeEvaluation = {
+    id: string | null;
+    visibility: string;
+    reason: string | null;
+    allowed: boolean;
+};
+export type ScopedMemoryResult<T> = {
+    mode: 'deny_by_default';
+    records: T[];
+    denied: MemoryScopeEvaluation[];
+    meta: {
+        evaluated_count: number;
+        returned_count: number;
+        denied_count: number;
+    };
+};
+export declare function normalizeMemoryAccessContext(input?: MemoryAccessContextInput): MemoryAccessContext;
+export declare function normalizeMemoryRecord(record: MemoryRecordInput): NormalizedMemoryRecord;
+export declare function evaluateMemoryScope(record: MemoryRecordInput, rawContext?: MemoryAccessContextInput): MemoryScopeEvaluation;
+export declare function buildScopedMemoryResult<T extends MemoryRecordInput>(records?: T[], context?: MemoryAccessContextInput): ScopedMemoryResult<T>;
+export declare function filterScopedMemoryRecords<T extends MemoryRecordInput>(records?: T[], context?: MemoryAccessContextInput): T[];

package/dist/memory-scope-policy.js

@@ -0,0 +1,159 @@
+// Moved from brainbase-unson server/services/memory-scope-policy.js without changing behavior.
+// Only type annotations were added; memory records stay open JSON objects as in the original.
+/* eslint-disable @typescript-eslint/no-explicit-any */
+const ROLE_RANK = {
+    member: 1,
+    gm: 2,
+    ceo: 3
+};
+function toList(value) {
+    if (Array.isArray(value)) {
+        return value.map(item => String(item).trim()).filter(Boolean);
+    }
+    if (typeof value === 'string') {
+        return value.split(',').map(item => item.trim()).filter(Boolean);
+    }
+    return [];
+}
+function firstString(...values) {
+    for (const value of values) {
+        if (typeof value === 'string' && value.trim())
+            return value.trim();
+    }
+    return null;
+}
+function parsePayload(record) {
+    if (!record || typeof record !== 'object')
+        return {};
+    const payload = record.payload;
+    if (typeof payload === 'string') {
+        try {
+            return JSON.parse(payload);
+        }
+        catch {
+            return {};
+        }
+    }
+    if (payload && typeof payload === 'object') {
+        return payload;
+    }
+    return record;
+}
+function normalizeRole(role) {
+    return typeof role === 'string' ? role.trim().toLowerCase() : '';
+}
+function maxRoleRank(roles) {
+    return roles.reduce((rank, role) => Math.max(rank, ROLE_RANK[normalizeRole(role)] || 0), 0);
+}
+export function normalizeMemoryAccessContext(input = {}) {
+    const roles = [
+        ...toList(input.roles),
+        ...toList(input.role)
+    ].map(normalizeRole).filter(Boolean);
+    const projectCodes = [
+        ...toList(input.project_codes),
+        ...toList(input.projectCodes)
+    ];
+    const clearance = [
+        ...toList(input.clearance),
+        ...toList(input.sensitivities),
+        ...toList(input.sensitivity)
+    ].map(item => item.toLowerCase());
+    return {
+        person_id: firstString(input.person_id, input.personId),
+        workspace: firstString(input.workspace),
+        channel_id: firstString(input.channel_id, input.channelId),
+        session_id: firstString(input.session_id, input.sessionId),
+        roles,
+        role_rank: maxRoleRank(roles),
+        project_codes: Array.from(new Set(projectCodes)),
+        clearance: Array.from(new Set(clearance))
+    };
+}
+export function normalizeMemoryRecord(record) {
+    const payload = parsePayload(record);
+    return {
+        id: firstString(payload.memory_candidate_id, payload.candidate_id, record?.id),
+        visibility: firstString(payload.visibility) || 'unknown',
+        owner_person_id: firstString(payload.owner_person_id, payload.ownerPersonId),
+        workspace: firstString(payload.workspace, record?.workspace),
+        channel_id: firstString(payload.channel_id, payload.channelId, record?.channel_id, record?.channelId),
+        project_code: firstString(payload.project_code, payload.projectCode, record?.project_code, record?.projectCode),
+        role_min: normalizeRole(firstString(payload.role_min, payload.roleMin, record?.role_min, record?.roleMin) || 'member'),
+        sensitivity: firstString(payload.sensitivity, record?.sensitivity) || 'internal'
+    };
+}
+function hasRequiredPolicy(context) {
+    return Boolean(context.person_id
+        && context.roles.length > 0
+        && context.project_codes.length > 0
+        && context.clearance.length > 0);
+}
+export function evaluateMemoryScope(record, rawContext = {}) {
+    const context = normalizeMemoryAccessContext(rawContext);
+    const memory = normalizeMemoryRecord(record);
+    const resultBase = {
+        id: memory.id,
+        visibility: memory.visibility,
+        reason: null
+    };
+    if (!hasRequiredPolicy(context)) {
+        return { ...resultBase, allowed: false, reason: 'missing_access_policy' };
+    }
+    if (!memory.id || memory.visibility === 'unknown') {
+        return { ...resultBase, allowed: false, reason: 'invalid_memory_record' };
+    }
+    if (memory.workspace && context.workspace && memory.workspace !== context.workspace) {
+        return { ...resultBase, allowed: false, reason: 'workspace_mismatch' };
+    }
+    if (memory.project_code && !context.project_codes.includes(memory.project_code)) {
+        return { ...resultBase, allowed: false, reason: 'project_mismatch' };
+    }
+    if (memory.channel_id && context.channel_id && memory.channel_id !== context.channel_id) {
+        return { ...resultBase, allowed: false, reason: 'channel_mismatch' };
+    }
+    const sensitivity = memory.sensitivity.toLowerCase();
+    if (!context.clearance.includes(sensitivity)) {
+        return { ...resultBase, allowed: false, reason: 'sensitivity_denied' };
+    }
+    if (context.role_rank < (ROLE_RANK[memory.role_min] || ROLE_RANK.member)) {
+        return { ...resultBase, allowed: false, reason: 'role_denied' };
+    }
+    if (memory.visibility === 'private' || memory.visibility === 'owner') {
+        const elevatedContext = context.roles.includes('gm') || context.roles.includes('ceo');
+        if (memory.owner_person_id !== context.person_id || elevatedContext) {
+            return { ...resultBase, allowed: false, reason: 'private_scope_denied' };
+        }
+        return { ...resultBase, allowed: true };
+    }
+    if (memory.visibility === 'project' || memory.visibility === 'role' || memory.visibility === 'team' || memory.visibility === 'org' || memory.visibility === 'public') {
+        return { ...resultBase, allowed: true };
+    }
+    return { ...resultBase, allowed: false, reason: 'visibility_denied' };
+}
+export function buildScopedMemoryResult(records = [], context = {}) {
+    const allowed = [];
+    const denied = [];
+    for (const record of records) {
+        const evaluation = evaluateMemoryScope(record, context);
+        if (evaluation.allowed) {
+            allowed.push(record);
+        }
+        else {
+            denied.push(evaluation);
+        }
+    }
+    return {
+        mode: 'deny_by_default',
+        records: allowed,
+        denied,
+        meta: {
+            evaluated_count: records.length,
+            returned_count: allowed.length,
+            denied_count: denied.length
+        }
+    };
+}
+export function filterScopedMemoryRecords(records = [], context = {}) {
+    return buildScopedMemoryResult(records, context).records;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@unson/brainbase-mcp",
-  "version": "0.31.0",
+  "version": "0.33.0",
   "description": "Local-first Brainbase judgment OS that lets supported AI agents reuse a user's approved goals, priorities, decisions, and judgment criteria.",
   "type": "module",
   "license": "MIT",
@@ -187,6 +187,14 @@
       "types": "./dist/judgment-resolution-contract.d.ts",
       "import": "./dist/judgment-resolution-contract.js"
     },
+    "./graph-maintenance-engine": {
+      "types": "./dist/graph-maintenance-engine.d.ts",
+      "import": "./dist/graph-maintenance-engine.js"
+    },
+    "./memory-scope-policy": {
+      "types": "./dist/memory-scope-policy.d.ts",
+      "import": "./dist/memory-scope-policy.js"
+    },
     "./canonical-document-writer": {
       "types": "./dist/canonical-document-writer.d.ts",
       "import": "./dist/canonical-document-writer.js"
@@ -455,5 +463,5 @@
   "engines": {
     "node": ">=20"
   },
-  "gitHead": "aeb8467e65eda4223dd092cc43d69b4ebd040f42"
+  "gitHead": "c3c5a1b3e4d5de936ecebc7ab86346bfdd49faf8"
 }

package/ui/world/world-canvas-ui.css

@@ -146,6 +146,14 @@
   font-weight: 700;
 }
 .bb-world-canvas-ui .bb-world-canvas-quest-text { overflow: hidden; white-space: nowrap; text-overflow: ellipsis; }
+/* A quest with a way down (候補の確認) is clickable even though the quest list lets the map take the pointer. */
+.bb-world-canvas-ui .bb-world-canvas-quest a {
+  flex: none;
+  color: #b5f2ab;
+  text-decoration: underline;
+  text-underline-offset: 2px;
+  pointer-events: auto;
+}
 
 .bb-world-canvas-ui .bb-world-canvas-edge {
   position: absolute;

package/ui/world/world-canvas-ui.js

@@ -357,13 +357,14 @@ export function createWorldCanvasUI({ doc, stage, reducedMotion = false, onReset
     activate('help', help);
     focus(helpTitle);
   }
-  function addNote({ label = '', text = '', tone = '', summary } = {}) {
+  function addNote({ label = '', text = '', tone = '', summary, link = null } = {}) {
     if (disposed) return;
     const note = element('section', 'bb-world-canvas-note');
     if (label) note.append(element('h3', '', label));
     if (text || summary) note.append(element('p', '', text || summary));
     if (label || text || summary) notes.append(note);
     if (typeof summary !== 'string' || !summary.trim()) return;
+    // A link (already checked by the caller) follows the summary so the quest is a way down, not only a sign.
     const quest = element('p', 'bb-world-canvas-quest');
     const icon = tone === 'attention' || tone === 'warning' ? '!' : 'i';
     quest.append(
@@ -373,6 +374,7 @@ export function createWorldCanvasUI({ doc, stage, reducedMotion = false, onReset
     // The accessible name contains the unabridged summary even when visual text
     // is ellipsized on a narrow canvas; the long explanation remains in help.
     quest.setAttribute('aria-label', summary.trim());
+    if (link?.href) quest.append(element('a', link.className ?? '', link.label ?? summary.trim(), { href: link.href }));
     quests.append(quest);
   }
   function clearNotes() {

package/ui/world/world-view.css

@@ -40,6 +40,7 @@
 }
 
 .bb-world-hud-line.is-attention { border-left-color: var(--bb-color-danger); }
+.bb-world-hud-line a { margin-left: 0.5em; color: inherit; text-decoration: underline; }
 .bb-world-hud-line.is-warning {
   border-left-color: var(--bb-color-warning);
   background: rgb(255 240 199 / 95%);

package/ui/world/world-view.js

@@ -33,7 +33,7 @@ import { createWorldCanvasUI } from './world-canvas-ui.js';
 import { workCanvasNotes } from './world-canvas-notes.js';
 import { canvasTexture, drawFacade, FACADE_SIZES, FACADE_UNITS, gableRoof, hashUnit, muted, paintVertices, roundedPlate, valueNoise } from './world-scenery.js';
 import { WORK_STATES, workCityBlocks, workGrowthBlock, workPickBlock, workSign, workSiteBlocks } from './world-work-rail.js';
-import { exitLegend, exitsRailBlock, normalizeBusinessExits } from './world-exits.js';
+import { exitHrefKind, exitLegend, exitsRailBlock, normalizeBusinessExits } from './world-exits.js';
 import {
   makeWorkspaceElement as el,
   workspacePageHeader,
@@ -1462,13 +1462,85 @@ function addressSelection() {
  *   label?, as_of? } }] }`.  `href` and `action.href` must be `https:` or a link inside the host (`/…`, `?…`);
  *   others are dropped and counted.  Without it the world is drawn exactly as before.
  * @typedef {{ status: string, read_at?: string, reason?: string, exits: object[] }} BusinessExitsAnswer
+ * @param {() => (MemoryStatusAnswer | Promise<MemoryStatusAnswer>)} [options.memoryStatus] How the memory loop stands
+ *   (story-world-memory-status-v1, ledger P18): last night's organizing and the memory candidates that wait for the
+ *   owner.  The answer is `{ status: 'available'|'partial'|'not_connected', night?: { status:
+ *   'completed'|'partial'|'failed'|'missing', finished_at? } | null, candidates?: { count } | null, review_href? }`.
+ *   A part that is null was not read and is shown as unknown, never as zero.  Without it the world says 未接続.
+ * @typedef {{ status: string, night?: object | null, candidates?: object | null, review_href?: string }} MemoryStatusAnswer
  */
+async function readMemoryStatus(memoryStatus) {
+  if (typeof memoryStatus !== 'function') return { status: 'not_connected' };
+  try {
+    const answer = await memoryStatus();
+    return answer && typeof answer === 'object' ? answer : { status: 'failed', reason: 'invalid_answer' };
+  } catch (error) {
+    return { status: 'failed', reason: error instanceof Error ? error.message : 'request_failed' };
+  }
+}
+
+const NIGHT_STATES = {
+  completed: { text: '済み', tone: 'info' },
+  partial: { text: '一部だけ（確かめられていない範囲があります）', tone: 'warning' },
+  failed: { text: 'できなかった（整理できなかった夜）', tone: 'attention' },
+  missing: { text: '動いていない（整理できなかった夜）', tone: 'attention' },
+};
+
+/** The memory loop as world notes (story-world-memory-status-v1).  Unknown is never shown as zero. */
+function memoryLines(answer) {
+  if (answer.status === 'not_connected') {
+    return [{ text: '記憶の整理：未接続。この画面は夜の整理の結果と記憶の候補を受け取れません。候補の件数は0件とは確認できません。', tone: 'info', summary: '記憶の整理：未接続' }];
+  }
+  if (answer.status !== 'available' && answer.status !== 'partial') {
+    return [{ text: `記憶の整理：読めない（${answer.reason ?? '理由不明'}）。候補の件数は0件とは確認できません。`, tone: 'warning', summary: '記憶の整理：読めない' }];
+  }
+  const lines = [];
+  const night = answer.night && NIGHT_STATES[answer.night.status];
+  if (night) {
+    const label = `昨夜の記憶の整理：${night.text}`;
+    lines.push({ text: `${label}。`, tone: night.tone, summary: night.tone === 'attention' ? '整理できなかった夜' : label });
+  } else {
+    lines.push({ text: '昨夜の記憶の整理：読めない。', tone: 'warning', summary: '昨夜の記憶の整理：読めない' });
+  }
+  const count = answer.candidates?.count;
+  if (Number.isInteger(count) && count >= 0) {
+    const href = typeof answer.review_href === 'string' && exitHrefKind(answer.review_href) ? answer.review_href : null;
+    const link = href && count > 0 ? { href, label: '候補の確認を開く', className: 'bb-world-memory-link' } : null;
+    if (count > 0) lines.push({ text: `あなたが決める記憶の候補 ${count}件。昇格したものだけが正本になります。`, tone: 'attention', summary: `あなたが決める記憶の候補 ${count}件`, link });
+    else lines.push({ text: 'あなたが決める記憶の候補はありません。', tone: 'info', summary: null });
+  } else {
+    lines.push({ text: '記憶の候補：読めない。件数は0件とは確認できません。', tone: 'warning', summary: '記憶の候補：読めない' });
+  }
+  return lines;
+}
+
+/** At most this many waiting judgments are listed in the world; the rest are counted, never hidden. */
+const WAITING_LIST_LIMIT = 3;
+
+/**
+ * The judgments waiting for the owner now, newest first, each a way down to the same judgment in
+ * 判断の履歴 (ledger P17 / U2).  The world stays an overview: only the exceptions become a short list.
+ */
+function waitingLines(proofs, judgmentHref) {
+  const waiting = [...proofs.values()]
+    .filter(isWaiting)
+    .sort((a, b) => String(b.proof?.recorded_at ?? '').localeCompare(String(a.proof?.recorded_at ?? '')));
+  const lines = waiting.slice(0, WAITING_LIST_LIMIT).map((item) => {
+    const id = item.proof.decision_attempt_id;
+    const question = item.proof.interruption?.question_display_text ?? item.proof.decision?.summary ?? id;
+    return { text: question, summary: question, link: { href: judgmentHref(id), label: '「判断の履歴」で開く', className: 'bb-world-waiting-link' } };
+  });
+  const rest = waiting.length - lines.length;
+  if (rest > 0) lines.push({ text: `ほか${rest}件は「判断の履歴」で見られます。`, summary: `ほか${rest}件の待っている判断`, link: null });
+  return lines;
+}
+
 /** 判断の履歴 in the local web (it was 今日, `#today`, until 2026-10-11; the shell still opens old links). */
 function defaultJudgmentHref(decisionAttemptId) {
   return decisionAttemptId ? `#value-proofs?decision=${encodeURIComponent(decisionAttemptId)}` : '#value-proofs';
 }
 
-export function createWorldView({ root, rail, page, presentation = 'standard', document: explicitDocument, fetcher, projectHref = (project) => `#projects?project=${encodeURIComponent(project.id)}`, taskHref = null, judgmentHref = defaultJudgmentHref, selection = addressSelection(), businessExits = null }) {
+export function createWorldView({ root, rail, page, presentation = 'standard', document: explicitDocument, fetcher, projectHref = (project) => `#projects?project=${encodeURIComponent(project.id)}`, taskHref = null, judgmentHref = defaultJudgmentHref, selection = addressSelection(), businessExits = null, memoryStatus = null }) {
   const exitsEnabled = typeof businessExits === 'function';
   const doc = explicitDocument ?? globalThis.document;
   const reducedMotion = Boolean(globalThis.matchMedia?.('(prefers-reduced-motion: reduce)').matches);
@@ -2311,6 +2383,7 @@ export function createWorldView({ root, rail, page, presentation = 'standard', d
   }
 
   async function load() {
+    const memoryRead = readMemoryStatus(memoryStatus);
     const businessesResult = await readJson(fetcher, '/api/extensions/world/businesses');
     if (disposed) return;
     // A world drawn from an organization's Graph shows only that organization's judgments: the host keeps
@@ -2333,13 +2406,14 @@ export function createWorldView({ root, rail, page, presentation = 'standard', d
     }
     if (disposed) return;
     notices.replaceChildren();
-    const note = (label, textValue, tone = 'info', summary = null) => {
+    const note = (label, textValue, tone = 'info', summary = null, link = null) => {
       if (canvasUI) {
-        setCanvasNote(`${label}:${summary ?? 'detail'}`, { label, text: textValue, tone, summary });
+        setCanvasNote(`${label}:${summary ?? 'detail'}`, { label, text: textValue, tone, summary, link });
         return;
       }
       const line = el(doc, 'p', { className: `bb-world-hud-line is-${tone}`, attrs: tone === 'info' ? {} : { role: 'alert' } });
       line.append(el(doc, 'strong', { text: label }), el(doc, 'span', { text: textValue }));
+      if (link) line.append(el(doc, 'a', { className: link.className, text: link.label, attrs: { href: link.href } }));
       notices.append(line);
     };
     const businessPayload = businessesResult.ok ? businessesResult.data : null;
@@ -2386,7 +2460,13 @@ export function createWorldView({ root, rail, page, presentation = 'standard', d
         note('判断', `${home.delegation_map.judged}件。作業した場所を読めないため、事業には置かず広場の種類別だけで描いています（${placesResult.ok ? placesResult.data?.reason ?? '理由不明' : placesResult.error}）。今あなたを待っている判断${waiting}件。`, 'warning', '判断の作業場所：読めない');
       }
     }
+    if (judgmentsConnected) {
+      for (const line of waitingLines(proofs, judgmentHref)) note('待っている判断', line.text, 'attention', line.summary, line.link);
+    }
     const rowItems = new Map(rows.map((row) => [row.key, Array.isArray(row.items) ? row.items : []]));
+    const memory = await memoryRead;
+    if (disposed) return;
+    for (const line of memoryLines(memory)) note('記憶', line.text, line.tone, line.summary, line.link);
 
     knownBusinesses = businesses;
     canvasUI?.setCities(businesses, current.code);