@jungjaehoon/mama-core 2.4.1 → 4.1.0

package/dist/knowledge/access.js

@@ -0,0 +1,663 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TwinRefNotVisibleError = void 0;
+exports.visibleTwinRefKeys = visibleTwinRefKeys;
+exports.visibleTwinRefKeysRecursive = visibleTwinRefKeysRecursive;
+exports.assertTwinRefsVisible = assertTwinRefsVisible;
+exports.listVisibleTwinEdgesForRefs = listVisibleTwinEdgesForRefs;
+exports.isChannelGranted = isChannelGranted;
+exports.channelGrantClause = channelGrantClause;
+const observations_js_1 = require("../knowledge/observations.js");
+const judgments_js_1 = require("./judgments.js");
+const TABLE_COLUMN_PRAGMAS = {
+    decisions: 'PRAGMA table_info(decisions)',
+    case_truth: 'PRAGMA table_info(case_truth)',
+};
+const tableColumnCache = new WeakMap();
+// Keep memory-truth quarantine semantics excluded for legacy/backcompat rows even though the
+// decisions.status terminal states: 'superseded' is history a caller holding
+// scope may read under includeReplaced; the rest are holds excluded always.
+const RETIRED_MEMORY_STATUSES = new Set(['quarantined', 'contradicted', 'stale']);
+class TwinRefNotVisibleError extends Error {
+    constructor(ref) {
+        super(`Twin ref is not visible to requested visibility: ${ref.kind}:${ref.id}`);
+        this.name = 'TwinRefNotVisibleError';
+    }
+}
+exports.TwinRefNotVisibleError = TwinRefNotVisibleError;
+function scopeKey(scope) {
+    return `${scope.kind}\0${scope.id}`;
+}
+function hasScopes(scopes) {
+    return Array.isArray(scopes) && scopes.length > 0;
+}
+function hasProjectRefs(projectRefs) {
+    return Array.isArray(projectRefs) && projectRefs.length > 0;
+}
+function asOfMs(visibility) {
+    return typeof visibility.asOfMs === 'number' ? visibility.asOfMs : null;
+}
+function startMs(visibility) {
+    return typeof visibility.startMs === 'number' ? visibility.startMs : null;
+}
+function isWithinVisibilityTime(value, visibility) {
+    const start = startMs(visibility);
+    const asOf = asOfMs(visibility);
+    if (start === null && asOf === null) {
+        return true;
+    }
+    return (typeof value === 'number' &&
+        (start === null || value >= start) &&
+        (asOf === null || value <= asOf));
+}
+function parseTimestamp(value) {
+    if (typeof value === 'number' && Number.isFinite(value)) {
+        return Math.floor(value);
+    }
+    if (typeof value === 'string') {
+        const trimmed = value.trim();
+        if (trimmed.length === 0) {
+            return null;
+        }
+        const numeric = Number(trimmed);
+        if (Number.isFinite(numeric)) {
+            return Math.floor(numeric);
+        }
+        const parsed = Date.parse(trimmed);
+        return Number.isFinite(parsed) ? parsed : null;
+    }
+    return null;
+}
+function tableColumns(adapter, table) {
+    const pragma = TABLE_COLUMN_PRAGMAS[table];
+    if (!pragma) {
+        throw new Error(`Unsupported table for column introspection: ${table}`);
+    }
+    let adapterCache = tableColumnCache.get(adapter);
+    if (!adapterCache) {
+        adapterCache = new Map();
+        tableColumnCache.set(adapter, adapterCache);
+    }
+    const cached = adapterCache.get(table);
+    if (cached) {
+        return cached;
+    }
+    const rows = adapter.prepare(pragma).all();
+    const columns = new Set(rows.map((row) => row.name));
+    adapterCache.set(table, columns);
+    return columns;
+}
+function isMemoryVisible(adapter, id, visibility) {
+    const columns = tableColumns(adapter, 'decisions');
+    const statusSelect = columns.has('status') ? 'status' : 'NULL AS status';
+    const supersededBySelect = columns.has('superseded_by')
+        ? 'superseded_by'
+        : 'NULL AS superseded_by';
+    const row = adapter
+        .prepare(`
+        SELECT created_at, event_datetime, ${statusSelect}, ${supersededBySelect}
+        FROM decisions
+        WHERE id = ?
+        LIMIT 1
+      `)
+        .get(id);
+    if (!row) {
+        return false;
+    }
+    const status = typeof row.status === 'string' ? row.status : 'active';
+    const replaced = status === 'superseded' ||
+        (typeof row.superseded_by === 'string' && row.superseded_by.length > 0);
+    if (RETIRED_MEMORY_STATUSES.has(status) || (replaced && !visibility.includeReplaced)) {
+        return false;
+    }
+    if (!isWithinVisibilityTime(row.event_datetime ?? row.created_at, visibility)) {
+        return false;
+    }
+    const scopes = visibility.scopes;
+    if (!hasScopes(scopes)) {
+        return true;
+    }
+    const scopeClauses = scopes.map(() => '(ms.kind = ? AND ms.external_id = ?)').join(' OR ');
+    const params = scopes.flatMap((scope) => [scope.kind, scope.id]);
+    const bindingRow = adapter
+        .prepare(`
+        SELECT 1 AS ok
+        FROM memory_scope_bindings msb
+        JOIN memory_scopes ms ON ms.id = msb.scope_id
+        WHERE msb.memory_id = ?
+          AND (${scopeClauses})
+        LIMIT 1
+      `)
+        .get(id, ...params);
+    if (bindingRow?.ok) {
+        return true;
+    }
+    if (columns.has('memory_scope_kind') && columns.has('memory_scope_id')) {
+        const row = adapter
+            .prepare(`
+          SELECT 1 AS ok
+          FROM decisions
+          WHERE id = ?
+            AND (${scopes.map(() => '(memory_scope_kind = ? AND memory_scope_id = ?)').join(' OR ')})
+          LIMIT 1
+        `)
+            .get(id, ...params);
+        return Boolean(row?.ok);
+    }
+    return false;
+}
+function parseCaseScopeRefs(scopeRefs) {
+    if (typeof scopeRefs !== 'string' || scopeRefs.length === 0) {
+        return [];
+    }
+    try {
+        const parsed = JSON.parse(scopeRefs);
+        if (!Array.isArray(parsed)) {
+            return [];
+        }
+        return parsed.filter((item) => item !== null &&
+            typeof item === 'object' &&
+            typeof item.kind === 'string' &&
+            typeof item.id === 'string');
+    }
+    catch {
+        return [];
+    }
+}
+function isCaseVisible(adapter, id, visibility) {
+    const row = adapter.prepare('SELECT * FROM case_truth WHERE case_id = ? LIMIT 1').get(id);
+    if (!row) {
+        return false;
+    }
+    const timestamp = parseTimestamp(row.last_activity_at) ?? parseTimestamp(row.updated_at);
+    if (!isWithinVisibilityTime(timestamp, visibility)) {
+        return false;
+    }
+    const scopes = visibility.scopes;
+    if (!hasScopes(scopes)) {
+        return true;
+    }
+    const requested = new Set(scopes.map(scopeKey));
+    const scopeRefs = parseCaseScopeRefs(row.scope_refs);
+    if (scopeRefs.some((scope) => requested.has(scopeKey(scope)))) {
+        return true;
+    }
+    const columns = tableColumns(adapter, 'case_truth');
+    if (columns.has('memory_scope_kind') && columns.has('memory_scope_id')) {
+        return scopes.some((scope) => row.memory_scope_kind === scope.kind && row.memory_scope_id === scope.id);
+    }
+    return false;
+}
+/** Current rows use immutable observation capture time; valid legacy rows use source time. */
+function isRawWithinTime(row, visibility) {
+    const maxSourceMs = visibility.maxSourceMs ?? null;
+    if (maxSourceMs !== null) {
+        if (!Number.isSafeInteger(maxSourceMs) || maxSourceMs < 0) {
+            throw new Error('Raw source ceiling must be a nonnegative epoch-millisecond integer');
+        }
+        const sourceAt = parseTimestamp(row.source_at);
+        if (sourceAt === null || sourceAt > maxSourceMs)
+            return false;
+    }
+    const rawTs = row.observation_observed_at ?? row.event_datetime ?? row.source_timestamp_ms;
+    if (rawTs === null || rawTs === undefined || (typeof rawTs === 'string' && rawTs.trim() === '')) {
+        return false;
+    }
+    const eventTsMs = parseTimestamp(rawTs);
+    return eventTsMs !== null && eventTsMs >= 0 && isWithinVisibilityTime(eventTsMs, visibility);
+}
+/**
+ * A `raw` ref resolves against observations, the same as an `observation` ref.
+ *
+ * There is one evidence space in the core. `raw` was the spelling from when the
+ * connector event index WAS the substrate -- the schema still shows it, allowing
+ * `raw` as an edge object and never as a subject, while `observation` is allowed
+ * on both sides. A ref that does not name an observation does not name evidence
+ * this core can vouch for, and is not visible.
+ */
+function isRawVisible(adapter, id, visibility) {
+    const row = adapter
+        .prepare(`SELECT source, channel, project_id, tenant_id, memory_scope_kind, memory_scope_id, source_at,
+              observed_at AS observation_observed_at
+         FROM observation_versions
+        WHERE observation_id = ?
+        LIMIT 1`)
+        .get(id);
+    return row ? isRawRowVisible(row, visibility) : false;
+}
+/** One observation row, judged against the caller's window. */
+function isRawRowVisible(row, visibility) {
+    if (Array.isArray(visibility.connectors) && !visibility.connectors.includes(String(row.source))) {
+        return false;
+    }
+    if (visibility.connectorWideRead?.includes(String(row.source))) {
+        return isRawWithinTime(row, visibility);
+    }
+    // The grant decides, and it decides the same way here as in the reader - one rule, taken
+    // from one place. The scope/project/tenant clauses below are the pre-grant rule and are
+    // skipped when a grant is present, exactly as the reader skips them, because applying
+    // both would make a cited ref satisfy a stricter test than a read one.
+    if (visibility.channels) {
+        return (isChannelGranted(String(row.source), typeof row.channel === 'string' ? row.channel : null, visibility.channels) && isRawWithinTime(row, visibility));
+    }
+    if (hasProjectRefs(visibility.projectRefs) &&
+        !visibility.projectRefs.some((project) => project.id === row.project_id)) {
+        return false;
+    }
+    if (typeof visibility.tenantId === 'string' &&
+        visibility.tenantId.length > 0 &&
+        row.tenant_id !== visibility.tenantId) {
+        return false;
+    }
+    if (!isRawWithinTime(row, visibility)) {
+        return false;
+    }
+    if (!hasScopes(visibility.scopes)) {
+        return true;
+    }
+    return visibility.scopes.some((scope) => row.memory_scope_kind === scope.kind && row.memory_scope_id === scope.id);
+}
+function refVisibilityKey(ref) {
+    return `${ref.kind}\0${ref.id}`;
+}
+function placeholders(count) {
+    if (count < 1) {
+        throw new Error('Visibility batch requires at least one identifier');
+    }
+    return Array.from({ length: count }, () => '?').join(', ');
+}
+function visibleTwinRefKeys(adapter, refs, visibility) {
+    const unique = [...new Map(refs.map((ref) => [refVisibilityKey(ref), ref])).values()];
+    const visible = new Set();
+    const ids = (kind) => unique.filter((ref) => ref.kind === kind).map((ref) => ref.id);
+    const rawIds = ids('raw');
+    if (rawIds.length > 0) {
+        const rows = adapter
+            .prepare(`SELECT observation_id, source, channel, project_id, tenant_id,
+                memory_scope_kind, memory_scope_id, source_at,
+                observed_at AS observation_observed_at
+           FROM observation_versions
+          WHERE observation_id IN (${placeholders(rawIds.length)})`)
+            .all(...rawIds);
+        for (const row of rows) {
+            if (isRawRowVisible(row, visibility)) {
+                visible.add(refVisibilityKey({ kind: 'raw', id: String(row.observation_id) }));
+            }
+        }
+    }
+    const observationIds = ids('observation');
+    if (observationIds.length > 0) {
+        const rows = adapter
+            .prepare(`SELECT observation_id, source, scope_json, observed_at, source_at
+           FROM observation_versions
+          WHERE observation_id IN (${placeholders(observationIds.length)})`)
+            .all(...observationIds);
+        for (const row of rows) {
+            if (isWithinVisibilityTime(row.observed_at, visibility) &&
+                (0, observations_js_1.isObservationVisibilityRowVisible)(row, {
+                    principalId: visibility.principalId,
+                    agentId: visibility.agentId,
+                    scopes: visibility.scopes,
+                    connectors: visibility.connectors,
+                    connectorWideRead: visibility.connectorWideRead,
+                    channels: visibility.channels,
+                    maxSourceMs: visibility.maxSourceMs,
+                })) {
+                visible.add(refVisibilityKey({ kind: 'observation', id: row.observation_id }));
+            }
+        }
+    }
+    const caseIds = ids('case');
+    if (caseIds.length > 0) {
+        const rows = adapter
+            .prepare(`SELECT * FROM case_truth WHERE case_id IN (${placeholders(caseIds.length)})`)
+            .all(...caseIds);
+        for (const row of rows) {
+            const timestamp = parseTimestamp(row.last_activity_at) ?? parseTimestamp(row.updated_at);
+            const scopeVisible = !hasScopes(visibility.scopes) ||
+                parseCaseScopeRefs(row.scope_refs).some((scope) => new Set(visibility.scopes?.map(scopeKey) ?? []).has(scopeKey(scope))) ||
+                visibility.scopes.some((scope) => row.memory_scope_kind === scope.kind && row.memory_scope_id === scope.id);
+            if (typeof row.case_id === 'string' &&
+                isWithinVisibilityTime(timestamp, visibility) &&
+                scopeVisible) {
+                visible.add(refVisibilityKey({ kind: 'case', id: row.case_id }));
+            }
+        }
+    }
+    const memoryIds = ids('memory');
+    if (memoryIds.length > 0) {
+        const columns = tableColumns(adapter, 'decisions');
+        const rows = adapter
+            .prepare(`SELECT * FROM decisions WHERE id IN (${placeholders(memoryIds.length)})`)
+            .all(...memoryIds);
+        const admittedBindings = new Set();
+        if (hasScopes(visibility.scopes)) {
+            const scopeClauses = visibility.scopes
+                .map(() => '(ms.kind = ? AND ms.external_id = ?)')
+                .join(' OR ');
+            const bindings = adapter
+                .prepare(`SELECT msb.memory_id FROM memory_scope_bindings msb
+             JOIN memory_scopes ms ON ms.id = msb.scope_id
+            WHERE msb.memory_id IN (${placeholders(memoryIds.length)})
+              AND (${scopeClauses})`)
+                .all(...memoryIds, ...visibility.scopes.flatMap((scope) => [scope.kind, scope.id]));
+            bindings.forEach((row) => admittedBindings.add(row.memory_id));
+        }
+        for (const row of rows) {
+            const id = String(row.id);
+            const status = typeof row.status === 'string' ? row.status : 'active';
+            const replaced = status === 'superseded' ||
+                (typeof row.superseded_by === 'string' && row.superseded_by.length > 0);
+            const retired = RETIRED_MEMORY_STATUSES.has(status) || (replaced && !visibility.includeReplaced);
+            const scopeVisible = !hasScopes(visibility.scopes) ||
+                admittedBindings.has(id) ||
+                (columns.has('memory_scope_kind') &&
+                    columns.has('memory_scope_id') &&
+                    visibility.scopes.some((scope) => row.memory_scope_kind === scope.kind && row.memory_scope_id === scope.id));
+            if (!retired &&
+                isWithinVisibilityTime(parseTimestamp(row.event_datetime) ?? parseTimestamp(row.created_at), visibility) &&
+                scopeVisible) {
+                visible.add(refVisibilityKey({ kind: 'memory', id }));
+            }
+        }
+    }
+    const registryIds = ids('registry');
+    if (registryIds.length > 0) {
+        // `created_at` is read, not just `id`: a registry ref must have existed at the requested
+        // `as_of`, the same rule memory, raw and observation refs obey. The entity branch this
+        // replaced applied it (`isWithinVisibilityTime(row.created_at, visibility)`) and the
+        // replacement dropped it, so a packet could cite a node created after the boundary.
+        //
+        // A merged-away node is NOT excluded. Merging redirects identity, it does not retire the
+        // node, and the graph projection's contract is to keep the ORIGINAL ref citable while
+        // resolving the current one beside it (design section 4.1, original/corrected references).
+        // Filtering on `merged_into IS NULL` here broke exactly that - caught by
+        // agent-graph.test.ts.
+        const rows = adapter
+            .prepare(`SELECT id, created_at FROM registry_nodes
+          WHERE id IN (${placeholders(registryIds.length)})`)
+            .all(...registryIds);
+        const admitted = new Set();
+        if (hasScopes(visibility.scopes)) {
+            const scopeClauses = visibility.scopes
+                .map(() => '(scope_kind = ? AND scope_id = ?)')
+                .join(' OR ');
+            const bindings = adapter
+                .prepare(`SELECT DISTINCT node_id FROM registry_scope_bindings
+            WHERE node_id IN (${placeholders(registryIds.length)}) AND (${scopeClauses})`)
+                .all(...registryIds, ...visibility.scopes.flatMap((scope) => [scope.kind, scope.id]));
+            bindings.forEach((row) => admitted.add(row.node_id));
+        }
+        for (const row of rows) {
+            if (isWithinVisibilityTime(row.created_at, visibility) &&
+                (!hasScopes(visibility.scopes) || admitted.has(row.id))) {
+                visible.add(refVisibilityKey({ kind: 'registry', id: row.id }));
+            }
+        }
+    }
+    for (const ref of unique) {
+        if (ref.kind === 'report' && !hasScopes(visibility.scopes)) {
+            visible.add(refVisibilityKey(ref));
+        }
+    }
+    return visible;
+}
+function preloadRecursiveEdgeVisibility(adapter, refs, visibility) {
+    const edgeCache = new Map();
+    const rootEdgeIds = [...new Set(refs.filter((ref) => ref.kind === 'edge').map((ref) => ref.id))];
+    const nestedRefs = refs.filter((ref) => ref.kind !== 'edge');
+    if (rootEdgeIds.length > 0) {
+        const rows = adapter
+            .prepare(`WITH RECURSIVE edge_tree(edge_id) AS (
+           SELECT CAST(value AS TEXT)
+             FROM json_each(?)
+           UNION
+           SELECT CAST(child.value AS TEXT)
+             FROM edge_tree tree
+             JOIN twin_edges parent ON parent.edge_id = tree.edge_id
+             JOIN json_each(json_array(
+               CASE WHEN parent.subject_kind = 'edge' THEN parent.subject_id END,
+               CASE WHEN parent.object_kind = 'edge' THEN parent.object_id END
+             )) child
+            WHERE child.value IS NOT NULL
+         )
+         SELECT edge.*
+           FROM edge_tree
+           JOIN twin_edges edge ON edge.edge_id = edge_tree.edge_id`)
+            .all(JSON.stringify(rootEdgeIds));
+        for (const row of rows) {
+            const edge = (0, judgments_js_1.mapTwinEdgeRow)(row);
+            edgeCache.set(edge.edge_id, edge);
+            if (edge.subject_ref.kind !== 'edge') {
+                nestedRefs.push(edge.subject_ref);
+            }
+            if (edge.object_ref.kind !== 'edge') {
+                nestedRefs.push(edge.object_ref);
+            }
+        }
+        for (const edgeId of rootEdgeIds) {
+            if (!edgeCache.has(edgeId)) {
+                edgeCache.set(edgeId, null);
+            }
+        }
+    }
+    return {
+        edgeCache,
+        edgeVisibility: new Map(),
+        precomputed: visibleTwinRefKeys(adapter, nestedRefs, visibility),
+    };
+}
+function visibleTwinRefKeysRecursive(adapter, refs, visibility) {
+    const { edgeCache, edgeVisibility, precomputed } = preloadRecursiveEdgeVisibility(adapter, refs, visibility);
+    const visible = new Set();
+    for (const ref of refs) {
+        if (isTwinRefVisible(adapter, ref, visibility, new Set(), edgeCache, edgeVisibility, precomputed)) {
+            visible.add(refVisibilityKey(ref));
+        }
+    }
+    return visible;
+}
+function isTwinRefVisible(adapter, ref, visibility, edgesInProgress, edgeCache, edgeVisibility, precomputed) {
+    if (precomputed && ref.kind !== 'edge') {
+        return precomputed.has(refVisibilityKey(ref));
+    }
+    if (ref.kind === 'report') {
+        return !hasScopes(visibility.scopes);
+    }
+    if (ref.kind === 'memory') {
+        return isMemoryVisible(adapter, ref.id, visibility);
+    }
+    if (ref.kind === 'case') {
+        return isCaseVisible(adapter, ref.id, visibility);
+    }
+    if (ref.kind === 'raw') {
+        return isRawVisible(adapter, ref.id, visibility);
+    }
+    if (ref.kind === 'registry') {
+        const node = adapter
+            .prepare('SELECT created_at FROM registry_nodes WHERE id = ?')
+            .get(ref.id);
+        if (!node || !isWithinVisibilityTime(node.created_at, visibility)) {
+            return false;
+        }
+        if (!hasScopes(visibility.scopes)) {
+            return true;
+        }
+        return visibility.scopes.some((scope) => Boolean(adapter
+            .prepare('SELECT 1 FROM registry_scope_bindings WHERE node_id = ? AND scope_kind = ? AND scope_id = ?')
+            .get(ref.id, scope.kind, scope.id)));
+    }
+    if (ref.kind === 'observation') {
+        const row = adapter
+            .prepare('SELECT scope_json, observed_at, source_at FROM observation_versions WHERE observation_id = ?')
+            .get(ref.id);
+        if (!row || !isWithinVisibilityTime(row.observed_at, visibility)) {
+            return false;
+        }
+        return (0, observations_js_1.isObservationVersionVisible)(adapter, ref.id, {
+            principalId: visibility.principalId,
+            agentId: visibility.agentId,
+            scopes: visibility.scopes,
+            connectors: visibility.connectors,
+            connectorWideRead: visibility.connectorWideRead,
+            channels: visibility.channels,
+            maxSourceMs: visibility.maxSourceMs,
+        });
+    }
+    if (ref.kind !== 'edge') {
+        throw new Error(`UNSUPPORTED_REFERENCE_KIND: ${ref.kind}`);
+    }
+    // An edge met again while it is being decided lies on a cycle through itself: never visible.
+    // Every edge on such a cycle is invisible from any root, so a finished answer is memoized.
+    if (edgesInProgress.has(ref.id)) {
+        return false;
+    }
+    const decided = edgeVisibility.get(ref.id);
+    if (decided !== undefined) {
+        return decided;
+    }
+    let edge = edgeCache.get(ref.id);
+    if (edge === undefined) {
+        edge = (0, judgments_js_1.getTwinEdge)(adapter, ref.id);
+        edgeCache.set(ref.id, edge);
+    }
+    if (!edge || !isWithinVisibilityTime(edge.created_at, visibility)) {
+        edgeVisibility.set(ref.id, false);
+        return false;
+    }
+    edgesInProgress.add(ref.id);
+    const visible = isTwinRefVisible(adapter, edge.subject_ref, visibility, edgesInProgress, edgeCache, edgeVisibility, precomputed) &&
+        isTwinRefVisible(adapter, edge.object_ref, visibility, edgesInProgress, edgeCache, edgeVisibility, precomputed);
+    edgesInProgress.delete(ref.id);
+    edgeVisibility.set(ref.id, visible);
+    return visible;
+}
+function assertTwinRefsVisible(adapter, refs, visibility = {}) {
+    const supportedKinds = new Set([
+        'memory',
+        'case',
+        'report',
+        'edge',
+        'raw',
+        'registry',
+        'observation',
+    ]);
+    for (const ref of refs) {
+        if (!supportedKinds.has(ref.kind)) {
+            throw new Error(`UNSUPPORTED_REFERENCE_KIND: ${ref.kind}`);
+        }
+    }
+    const { edgeCache, edgeVisibility, precomputed } = preloadRecursiveEdgeVisibility(adapter, refs, visibility);
+    for (const ref of refs) {
+        if (!isTwinRefVisible(adapter, ref, visibility, new Set(), edgeCache, edgeVisibility, precomputed)) {
+            throw new TwinRefNotVisibleError(ref);
+        }
+    }
+}
+function listVisibleTwinEdgesForRefs(adapter, refs, options = {}) {
+    const edgeTypes = normalizeEdgeTypes(options.edgeTypes);
+    const limit = typeof options.limit === 'number' && Number.isFinite(options.limit)
+        ? Math.max(0, Math.floor(options.limit))
+        : null;
+    if (limit === 0) {
+        return [];
+    }
+    if (limit !== null) {
+        const pageSize = Math.min(2000, Math.max(128, limit * 2));
+        const admitted = [];
+        let after;
+        while (admitted.length < limit) {
+            const candidates = (0, judgments_js_1.listTwinEdgesForRefs)(adapter, refs, {
+                newest: true,
+                limit: pageSize,
+                ...(after ? { after } : {}),
+                ...(edgeTypes.size > 0 ? { edgeTypes: [...edgeTypes] } : {}),
+                startMs: options.startMs,
+                asOfMs: options.asOfMs,
+            });
+            if (candidates.length === 0) {
+                break;
+            }
+            const { edgeCache, edgeVisibility, precomputed } = preloadRecursiveEdgeVisibility(adapter, candidates.flatMap((edge) => [edge.subject_ref, edge.object_ref]), options);
+            for (const edge of candidates) {
+                if (isTwinRefVisible(adapter, edge.subject_ref, options, new Set(), edgeCache, edgeVisibility, precomputed) &&
+                    isTwinRefVisible(adapter, edge.object_ref, options, new Set(), edgeCache, edgeVisibility, precomputed)) {
+                    admitted.push(edge);
+                    if (admitted.length === limit) {
+                        return admitted;
+                    }
+                }
+            }
+            if (candidates.length < pageSize) {
+                break;
+            }
+            const last = candidates[candidates.length - 1];
+            after = { createdAt: last.created_at, edgeId: last.edge_id };
+        }
+        return admitted;
+    }
+    const candidateEdges = (0, judgments_js_1.listTwinEdgesForRefs)(adapter, refs);
+    const { edgeCache, edgeVisibility, precomputed } = preloadRecursiveEdgeVisibility(adapter, candidateEdges.flatMap((edge) => [edge.subject_ref, edge.object_ref]), options);
+    const edges = candidateEdges.filter((edge) => (edgeTypes.size === 0 || edgeTypes.has(edge.edge_type)) &&
+        (typeof options.startMs !== 'number' || edge.created_at >= options.startMs) &&
+        (typeof options.asOfMs !== 'number' || edge.created_at <= options.asOfMs) &&
+        isTwinRefVisible(adapter, edge.subject_ref, options, new Set(), edgeCache, edgeVisibility, precomputed) &&
+        isTwinRefVisible(adapter, edge.object_ref, options, new Set(), edgeCache, edgeVisibility, precomputed));
+    const sortedEdges = [...edges].sort((left, right) => {
+        const createdDiff = right.created_at - left.created_at;
+        return createdDiff !== 0 ? createdDiff : left.edge_id.localeCompare(right.edge_id);
+    });
+    return sortedEdges;
+}
+function normalizeEdgeTypes(edgeTypes) {
+    if (!Array.isArray(edgeTypes) || edgeTypes.length === 0) {
+        return new Set();
+    }
+    return new Set(edgeTypes);
+}
+/**
+ * The rule: an event is visible when its connector is granted and its channel is one of
+ * the channels granted for that connector.
+ *
+ * A connector absent from the grant is denied. A connector present with an empty list is
+ * also denied - "granted the connector but no channel of it" is not a useful state, and
+ * reading it as "all channels" is how a grant becomes a wildcard.
+ */
+function isChannelGranted(connector, channel, grant) {
+    if (typeof channel !== 'string' || channel.length === 0)
+        return false;
+    const channels = grant[connector];
+    return Array.isArray(channels) && channels.includes(channel);
+}
+/**
+ * The same rule as a SQL predicate.
+ *
+ * Returns null when nothing is readable, which callers must treat as "select nothing"
+ * rather than "no filter" - an empty WHERE is how a visibility rule turns into a full scan
+ * at the exact moment it should have refused.
+ *
+ * `requestedConnectors` narrows further: a connector the caller did not ask for is not read
+ * even though it is granted. The grant is a ceiling, never an instruction.
+ */
+function channelGrantClause(grant, requestedConnectors, columns) {
+    const pairs = [];
+    const params = [];
+    for (const [connector, channels] of Object.entries(grant)) {
+        if (Array.isArray(requestedConnectors) && !requestedConnectors.includes(connector))
+            continue;
+        // Array.isArray, not `?? []`: the boolean form denies a malformed grant quietly, so
+        // this one must not throw on it. Two forms of a rule that disagree on bad input have
+        // already started to be two rules.
+        if (!Array.isArray(channels))
+            continue;
+        const unique = [
+            ...new Set(channels.filter((channel) => typeof channel === 'string' && channel.length > 0)),
+        ];
+        if (unique.length === 0)
+            continue;
+        pairs.push(`(${columns.connector} = ? AND ${columns.channel} IN (${unique.map(() => '?').join(', ')}))`);
+        params.push(connector, ...unique);
+    }
+    return pairs.length === 0 ? null : { sql: `(${pairs.join(' OR ')})`, params };
+}
+//# sourceMappingURL=access.js.map

package/dist/knowledge/case-errors.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Case errors.
+ *
+ * `CaseMergeChainCycleError` used to live in `entities/errors.ts` and extend
+ * that module's `EntityError`. Nothing about a cycle in `case_truth` belongs to
+ * the entity substrate; it sat there because the two subsystems were written
+ * together. It carries its own shape now.
+ *
+ * @module cases/errors
+ */
+export interface CaseErrorEnvelope {
+    error: {
+        code: string;
+        message: string;
+        hint: string;
+        doc_url: string;
+    };
+}
+export declare class CaseMergeChainCycleError extends Error {
+    readonly code = "case.merge_chain_cycle";
+    readonly doc_section = "#case-merge-chain-cycle";
+    readonly context: Record<string, unknown>;
+    readonly hint: string;
+    constructor(context: {
+        case_id: string;
+        chain: string[];
+        detected_at_depth: number;
+    });
+    toErrorEnvelope(): CaseErrorEnvelope;
+}
+//# sourceMappingURL=case-errors.d.ts.map