@shieldaai/agent-map 0.1.0-alpha.3 → 1.1.0

package/dist/store/ancestors.d.ts

@@ -0,0 +1,9 @@
+import { type MapSource } from '../types.js';
+import { StoreRead } from './read.js';
+/**
+ * Delegation ancestors last, after every source's own nodes and edges, so they never crowd out
+ * an agent's own evidence: each source's ancestors are added only if they fit what is left of
+ * the node, edge and byte budgets (keeping a quarter of the bytes for evidence). Otherwise none
+ * are added and the projection says so.
+ */
+export declare function loadAncestors(read: StoreRead, sources: MapSource[]): Promise<void>;

package/dist/store/ancestors.js

@@ -0,0 +1,86 @@
+import neo4j from 'neo4j-driver';
+import { MapQueryError } from '../types.js';
+import { safeNode, text } from './nodes.js';
+import { ANCESTOR_TASKS, ANCESTORS, EDGES } from './queries.js';
+import { StoreRead } from './read.js';
+/**
+ * Delegation ancestors last, after every source's own nodes and edges, so they never crowd out
+ * an agent's own evidence: each source's ancestors are added only if they fit what is left of
+ * the node, edge and byte budgets (keeping a quarter of the bytes for evidence). Otherwise none
+ * are added and the projection says so.
+ */
+export async function loadAncestors(read, sources) {
+    const { accessMode } = read;
+    for (const job of read.ancestorJobs) {
+        const index = sources.findIndex(item => item.id === job.sourceId);
+        const current = sources[index].current;
+        const loaded = new Set(current.nodes.map(node => node.id));
+        const entities = new Set(current.nodes.map(node => node.entityId));
+        const nodeRoom = read.limits.nodes - read.nodeCount;
+        const found = [];
+        const foundIds = new Set();
+        await read.run(ANCESTORS[accessMode], {
+            ...job.params,
+            GuardDeploymentIds: current.nodes.filter(node => node.label === 'GuardDeployment').map(node => node.id),
+            nodeLimit: neo4j.int(read.limits.nodes + 1),
+        }, item => {
+            const ancestor = text(item.get('id'));
+            if (!loaded.has(ancestor) && !foundIds.has(ancestor) && found.length <= nodeRoom) {
+                foundIds.add(ancestor);
+                found.push(ancestor);
+            }
+        });
+        let notLoaded = found.length > nodeRoom;
+        const records = [], extra = [];
+        if (!notLoaded && found.length) {
+            const requested = new Set(found);
+            await read.run(ANCESTOR_TASKS, { ...job.params, ancestorTaskIds: found, nodeLimit: neo4j.int(found.length + 1) }, item => {
+                if (item.get('label') !== 'GuardTask')
+                    throw new MapQueryError('MAP_UNAVAILABLE');
+                const node = safeNode(item.get('node'), 'GuardTask', job.sourceId, current.id);
+                // Each requested id once: a second node with the same id is malformed.
+                if (!requested.delete(node.id) || entities.has(node.entityId))
+                    throw new MapQueryError('MAP_UNAVAILABLE');
+                entities.add(node.entityId);
+                records.push(node);
+            });
+            // Only delegation and handoff edges touch ancestors (their grants and deployments
+            // are not read).
+            const ancestorSet = new Set(records.map(node => node.id));
+            const taskIds = [
+                ...current.nodes.filter(node => node.label === 'GuardTask').map(node => node.id),
+                ...ancestorSet,
+            ];
+            const tasks = new Set(taskIds);
+            const edgeRoom = read.limits.edges - read.edgeCount;
+            await read.run(EDGES, {
+                ...job.params,
+                nodeIds: taskIds,
+                relationships: ['G_DELEGATED_FROM', 'G_DERIVED_FROM'],
+                edgeLimit: neo4j.int(read.limits.edges + 1),
+            }, item => {
+                const source = text(item.get('source')), target = text(item.get('target'));
+                const kind = item.get('kind');
+                if ((kind !== 'G_DELEGATED_FROM' && kind !== 'G_DERIVED_FROM') || !tasks.has(source) || !tasks.has(target))
+                    throw new MapQueryError('MAP_UNAVAILABLE');
+                if (!ancestorSet.has(source) && !ancestorSet.has(target))
+                    return;
+                if (extra.length <= edgeRoom)
+                    extra.push({ source, target, kind });
+            });
+            const bytes = Buffer.byteLength(JSON.stringify([records, extra]), 'utf8');
+            notLoaded = extra.length > edgeRoom || read.materializedBytes + bytes > read.limits.bytes * 0.75;
+            if (!notLoaded) {
+                read.charge([records, extra]);
+                read.nodeCount += records.length;
+                read.edgeCount += extra.length;
+            }
+        }
+        sources[index] = {
+            ...sources[index],
+            current: notLoaded
+                ? { ...current, ancestorsNotLoaded: true }
+                : { ...current, nodes: [...current.nodes, ...records], edges: [...current.edges, ...extra] },
+        };
+    }
+}

package/dist/store/discovery.d.ts

@@ -0,0 +1,8 @@
+import { type MapView } from '../types.js';
+import { StoreRead } from './read.js';
+/**
+ * Discovery reads load no nodes: fixed, bounded queries per source, then the same publication
+ * recheck as every other read. `undeclared` counts (and pages) activity no declared agent
+ * accounts for; `unclaimedIdentities` lists IAM roles and users no declared binding names.
+ */
+export declare function readDiscovery(read: StoreRead): Promise<MapView>;

package/dist/store/discovery.js

@@ -0,0 +1,288 @@
+import neo4j from 'neo4j-driver';
+import { immutableJson } from '@shieldaai/agent-guard/internal';
+import { collectionKey } from '../policy-reader.js';
+import { MAP_LABELS, MapQueryError, } from '../types.js';
+import { converted, coreCaptureTimes, coverage, text } from './nodes.js';
+import { AWS_COLLECTION_COLUMNS, AWS_COLLECTION_LIMIT, AWS_COLLECTIONS, AWS_MEMBER_LIMIT, BINDINGS_WITHOUT_IDENTITY, CLAIM_LIMIT, CLAIMED_IDENTITIES, UNCLAIMED_COUNTS, UNCLAIMED_PAGE, UNDECLARED_COUNT_LIMIT, UNDECLARED_COUNTS, UNDECLARED_PRINCIPALS, UNDECLARED_TASKS, } from './queries.js';
+import { StoreRead } from './read.js';
+/**
+ * Discovery reads load no nodes: fixed, bounded queries per source, then the same publication
+ * recheck as every other read. `undeclared` counts (and pages) activity no declared agent
+ * accounts for; `unclaimedIdentities` lists IAM roles and users no declared binding names.
+ */
+export async function readDiscovery(read) {
+    const { scope, selection } = read;
+    const malformed = () => {
+        throw new MapQueryError('MAP_UNAVAILABLE');
+    };
+    const whole = (value, maximum) => {
+        const number = converted(value);
+        return typeof number === 'number' && Number.isSafeInteger(number) && number >= 0 && number <= maximum
+            ? number
+            : malformed();
+    };
+    const flag = (value) => value === null || value === undefined ? null : typeof value === 'boolean' ? value : malformed();
+    const page = selection.page;
+    const listed = [];
+    const claimed = new Set();
+    let claimsExceeded = false;
+    let bindingsWithoutIdentity = false;
+    // The strictest enrolled cloud age per tenant, under the host ceiling.
+    const maximumAges = new Map();
+    for (const record of read.selected) {
+        const sourceId = text(record.get('id'));
+        const tenantId = text(record.get('tenantId'));
+        const currentId = text(record.get('currentId'));
+        const profile = record.get('profile');
+        if (!scope.tenantIds.includes(tenantId) || !['core', 'host', 'host-mcp'].includes(profile))
+            malformed();
+        const params = { ...read.common, sourceId, tenantId, projectionId: currentId, labels: [...MAP_LABELS] };
+        const captures = coreCaptureTimes(record.get('currentCoverage'));
+        let undeclared;
+        if (selection.undeclared === true) {
+            const counts = await read.run(UNDECLARED_COUNTS, {
+                ...params,
+                countLimit: neo4j.int(UNDECLARED_COUNT_LIMIT + 1),
+            });
+            if (counts.length !== 1)
+                malformed();
+            const tasks = whole(counts[0].get('tasks'), UNDECLARED_COUNT_LIMIT + 1);
+            const principals = whole(counts[0].get('principals'), UNDECLARED_COUNT_LIMIT + 1);
+            let listing;
+            if (page !== undefined) {
+                const paging = { ...params, pageOffset: neo4j.int(page.offset), pageLimit: neo4j.int(page.limit) };
+                const seen = new Set();
+                // A second row for one entity is malformed, never a longer list.
+                const once = (id) => {
+                    if (seen.has(id))
+                        malformed();
+                    seen.add(id);
+                    return id;
+                };
+                if (page.kind === 'tasks') {
+                    const items = [];
+                    await read.run(UNDECLARED_TASKS, paging, item => {
+                        if (items.length >= page.limit)
+                            malformed();
+                        const tools = converted(item.get('tools'));
+                        if (!Array.isArray(tools) || tools.length > 33)
+                            malformed();
+                        const names = [...new Set(tools.map(tool => text(tool)))].sort();
+                        const principalId = item.get('principalId');
+                        const parentDeclared = item.get('parentDeclared');
+                        if (typeof parentDeclared !== 'boolean')
+                            malformed();
+                        const row = {
+                            id: once(text(item.get('id'))),
+                            taskId: text(item.get('taskId')),
+                            principalId: principalId === null || principalId === undefined ? null : text(principalId),
+                            delegated: flag(item.get('delegated')),
+                            derived: flag(item.get('derived')),
+                            revoked: flag(item.get('revoked')),
+                            parentDeclared,
+                            tools: names.slice(0, 32),
+                            toolsTruncated: tools.length > 32,
+                        };
+                        read.charge(row);
+                        items.push(row);
+                    });
+                    listing = { kind: 'tasks', items };
+                }
+                else {
+                    const items = [];
+                    await read.run(UNDECLARED_PRINCIPALS, paging, item => {
+                        if (items.length >= page.limit)
+                            malformed();
+                        const tasks = whole(item.get('tasks'), 1001);
+                        const row = {
+                            id: once(text(item.get('id'))),
+                            principalId: text(item.get('principalId')),
+                            tasks: Math.min(tasks, 1000),
+                            tasksCapped: tasks > 1000,
+                        };
+                        read.charge(row);
+                        items.push(row);
+                    });
+                    listing = { kind: 'principals', items };
+                }
+            }
+            undeclared = {
+                tasks: Math.min(tasks, UNDECLARED_COUNT_LIMIT),
+                tasksCapped: tasks > UNDECLARED_COUNT_LIMIT,
+                principals: Math.min(principals, UNDECLARED_COUNT_LIMIT),
+                principalsCapped: principals > UNDECLARED_COUNT_LIMIT,
+                ...(listing ? { page: listing } : {}),
+            };
+        }
+        else {
+            const enrolled = record.get('policyCoverage');
+            if (enrolled !== null && enrolled !== undefined)
+                maximumAges.set(tenantId, Math.min(maximumAges.get(tenantId) ?? read.limits.policyAge, read.maximumAgeFor(enrolled)));
+            if (!claimsExceeded)
+                await read.run(CLAIMED_IDENTITIES, { ...params, claimLimit: neo4j.int(CLAIM_LIMIT - claimed.size + 1) }, item => {
+                    const arn = item.get('arn');
+                    if (typeof arn !== 'string' || !arn || arn.length > 2048)
+                        malformed();
+                    claimed.add(arn);
+                    if (claimed.size > CLAIM_LIMIT)
+                        claimsExceeded = true;
+                });
+            if (!bindingsWithoutIdentity) {
+                const [open] = await read.run(BINDINGS_WITHOUT_IDENTITY, params);
+                // Only an explicit "none" clears it.
+                bindingsWithoutIdentity = open?.get('open') !== false;
+            }
+        }
+        listed.push({
+            id: sourceId,
+            tenantId,
+            sourceId: text(record.get('nativeSourceId')),
+            profile,
+            current: {
+                id: currentId,
+                snapshotId: text(record.get('currentSnapshotId')),
+                generatedAt: text(record.get('currentGeneratedAt')),
+                status: 'published',
+                nodes: [],
+                edges: [],
+                // Only what this read rests on: when the tasks were captured.
+                coverage: { tasks: { status: 'complete', ...(captures.tasks ? { observedAt: captures.tasks } : {}) } },
+                ...(undeclared ? { undeclared } : {}),
+            },
+            previous: null,
+        });
+    }
+    let unclaimedIdentities;
+    if (selection.unclaimedIdentities === true) {
+        const readCollections = async () => (await read.run(AWS_COLLECTIONS, { ...read.common, collectionLimit: neo4j.int(AWS_COLLECTION_LIMIT + 1) })).map(item => Object.fromEntries(AWS_COLLECTION_COLUMNS.map(column => [column, converted(item.get(column))])));
+        const collections = await readCollections();
+        if (collections.length > AWS_COLLECTION_LIMIT)
+            throw new MapQueryError('MAP_LIMIT_EXCEEDED');
+        const stamp = read.now();
+        const claims = [...claimed].sort();
+        const accounts = [];
+        const complete = new Map();
+        let total = 0;
+        for (const collection of collections) {
+            const { tenantId, partition, accountId, capturedAt } = collection;
+            // Without these the account cannot even be named.
+            if (typeof tenantId !== 'string' ||
+                !scope.tenantIds.includes(tenantId) ||
+                typeof partition !== 'string' ||
+                !['aws', 'aws-cn', 'aws-us-gov'].includes(partition) ||
+                typeof accountId !== 'string' ||
+                !/^[0-9]{12}$/.test(accountId)) {
+                malformed();
+                continue;
+            }
+            const account = (reason, observedAt, counts = null) => ({
+                tenantId,
+                partition,
+                accountId,
+                status: reason === null && counts ? 'complete' : 'unknown',
+                reason,
+                observedAt,
+                observed: counts?.observed ?? null,
+                unclaimed: counts?.unclaimed ?? null,
+            });
+            const id = collection.id;
+            if (typeof id !== 'string' ||
+                id !== collectionKey(scope.companyId, tenantId, partition, accountId) ||
+                complete.has(id) ||
+                collection.schemaVersion !== 1 ||
+                collection.status !== 'complete' ||
+                typeof collection.contentHash !== 'string' ||
+                !/^[a-f0-9]{64}$/.test(collection.contentHash) ||
+                typeof capturedAt !== 'number' ||
+                !Number.isSafeInteger(capturedAt) ||
+                capturedAt < 0 ||
+                capturedAt > stamp) {
+                accounts.push(account('collection_invalid', null));
+                continue;
+            }
+            const observedAt = new Date(capturedAt * 1000).toISOString();
+            if (stamp - capturedAt > (maximumAges.get(tenantId) ?? read.limits.policyAge)) {
+                accounts.push(account('stale', observedAt));
+                continue;
+            }
+            // Without the full set of claims, "unclaimed" would overstate.
+            if (claimsExceeded) {
+                accounts.push(account('claims_limit_exceeded', observedAt));
+                continue;
+            }
+            const counted = await read.run(UNCLAIMED_COUNTS, {
+                ...read.common,
+                collectionId: id,
+                collectionTenantId: tenantId,
+                claimed: claims,
+                memberLimit: neo4j.int(AWS_MEMBER_LIMIT + 1),
+            });
+            if (counted.length !== 1)
+                malformed();
+            const observed = whole(counted[0].get('observed'), AWS_MEMBER_LIMIT + 1);
+            const unclaimed = whole(counted[0].get('unclaimed') ?? 0, AWS_MEMBER_LIMIT + 1);
+            const inconsistent = whole(counted[0].get('inconsistent') ?? 0, AWS_MEMBER_LIMIT + 1);
+            if (observed > AWS_MEMBER_LIMIT)
+                accounts.push(account('limit_exceeded', observedAt));
+            else if (inconsistent)
+                accounts.push(account('changed', observedAt));
+            else {
+                const judged = account(null, observedAt, { observed, unclaimed });
+                accounts.push(judged);
+                complete.set(id, judged);
+                total += unclaimed;
+            }
+        }
+        const identities = [];
+        if (page !== undefined && complete.size && page.offset < total)
+            await read.run(UNCLAIMED_PAGE, {
+                ...read.common,
+                collectionIds: [...complete.keys()],
+                claimed: claims,
+                pageOffset: neo4j.int(page.offset),
+                pageLimit: neo4j.int(page.limit),
+            }, item => {
+                const account = complete.get(item.get('collectionId'));
+                const arn = item.get('arn'), name = item.get('name'), path = item.get('path');
+                const role = item.get('role'), user = item.get('user');
+                // The same shape the collector accepted: one kind, and an ARN built from its parts.
+                if (identities.length >= page.limit ||
+                    !account ||
+                    typeof role !== 'boolean' ||
+                    typeof user !== 'boolean' ||
+                    role === user ||
+                    typeof name !== 'string' ||
+                    !/^[A-Za-z0-9+=,.@_-]{1,128}$/.test(name) ||
+                    typeof path !== 'string' ||
+                    path.length > 512 ||
+                    !/^\/(?:[\x21-\x7e]+\/)?$/.test(path) ||
+                    arn !== `arn:${account.partition}:iam::${account.accountId}:${role ? 'role' : 'user'}${path}${name}` ||
+                    claimed.has(arn)) {
+                    malformed();
+                    return;
+                }
+                const row = {
+                    arn,
+                    kind: role ? 'role' : 'user',
+                    name,
+                    path,
+                    tenantId: account.tenantId,
+                    partition: account.partition,
+                    accountId: account.accountId,
+                };
+                read.charge(row);
+                identities.push(row);
+            });
+        // A collection published during the read would mix two captures.
+        if (JSON.stringify(collections) !== JSON.stringify(await readCollections()))
+            malformed();
+        unclaimedIdentities = { accounts, identities, total, bindingsWithoutIdentity };
+    }
+    await read.recheckSources();
+    try {
+        return immutableJson({ sources: listed, ...(unclaimedIdentities ? { unclaimedIdentities } : {}) }, 16, 200_000, 4 * 1024 * 1024);
+    }
+    catch {
+        throw new MapQueryError('MAP_LIMIT_EXCEEDED');
+    }
+}

package/dist/store/evidence.d.ts

@@ -0,0 +1,12 @@
+import { type IdentityScopePlan, type PolicyPlan } from '../policy-reader.js';
+import { type JsonObject } from '../types.js';
+import { StoreRead } from './read.js';
+/** Identity-scope rows for one plan, each bounded; a row that is too large stands in as truncated. */
+export declare function readScopeRows(read: StoreRead, plan: IdentityScopePlan, params: Record<string, unknown>, chargeRows: boolean): Promise<JsonObject[]>;
+/** Policy rows for one plan, bounded in count and bytes. */
+export declare function readPolicyRows(read: StoreRead, plan: PolicyPlan, params: Record<string, unknown>, chargeRows: boolean): Promise<JsonObject[]>;
+/**
+ * Reads every piece of evidence a second time, after the publication recheck: if a row, a
+ * classification or an identity-scope record changed while the read ran, the read is refused.
+ */
+export declare function verifyEvidence(read: StoreRead): Promise<void>;

package/dist/store/evidence.js

@@ -0,0 +1,90 @@
+import neo4j from 'neo4j-driver';
+import { IDENTITY_SCOPE_COLUMNS, IDENTITY_SCOPE_QUERY, identityScopeEvidence, identityScopeParameters, POLICY_COLUMNS, POLICY_QUERY, policyEvidence, policyParameters, safeIdentityScopeRow, safePolicyRow, } from '../policy-reader.js';
+import { MapQueryError } from '../types.js';
+import { boundedRecords, converted, oversized, sortedBySerialization } from './nodes.js';
+import { checked, scoped } from './queries.js';
+import { StoreRead } from './read.js';
+/** Identity-scope rows for one plan, each bounded; a row that is too large stands in as truncated. */
+export async function readScopeRows(read, plan, params, chargeRows) {
+    if (!plan.probes.length)
+        return [];
+    const rows = [];
+    let readBytes = 0;
+    await read.run(IDENTITY_SCOPE_QUERY, {
+        ...params,
+        scopePairs: identityScopeParameters(plan),
+        candidateLimit: neo4j.int(plan.candidateLimit),
+        buckets: plan.buckets,
+        // A malformed fan-out repeats a probe's row; the classifier marks that one record
+        // invalid, so only a much larger blow-up fails the whole read.
+        scopeRowLimit: neo4j.int(plan.probes.length * 8 + 1),
+    }, item => {
+        if (rows.length >= plan.probes.length * 8)
+            throw new MapQueryError('MAP_LIMIT_EXCEEDED');
+        const raw = Object.fromEntries(IDENTITY_SCOPE_COLUMNS.map(column => [column, converted(item.get(column))]));
+        // An identity whose row is too large, or arrives after the read's byte budget, is
+        // reported truncated for that identity only; the rest of the read stands.
+        let safe;
+        try {
+            safe = safeIdentityScopeRow(raw);
+        }
+        catch {
+            safe = oversized(raw.key);
+        }
+        const bytes = Buffer.byteLength(JSON.stringify(safe), 'utf8');
+        if (readBytes + bytes > 4 * 1024 * 1024)
+            safe = oversized(raw.key);
+        else
+            readBytes += bytes;
+        if (chargeRows)
+            read.charge(safe);
+        rows.push(safe);
+    });
+    return sortedBySerialization(rows);
+}
+/** Policy rows for one plan, bounded in count and bytes. */
+export async function readPolicyRows(read, plan, params, chargeRows) {
+    if (!plan.probes.length)
+        return [];
+    const rows = [];
+    let readBytes = 0;
+    const pairs = policyParameters(plan);
+    if (Buffer.byteLength(JSON.stringify(pairs), 'utf8') > 4 * 1024 * 1024)
+        throw new MapQueryError('MAP_LIMIT_EXCEEDED');
+    await read.run(POLICY_QUERY, { ...params, policyPairs: pairs, policyRowLimit: neo4j.int(plan.probes.length * 3 + 1) }, item => {
+        if (rows.length >= plan.probes.length * 3)
+            throw new MapQueryError('MAP_LIMIT_EXCEEDED');
+        const raw = Object.fromEntries(POLICY_COLUMNS.map(column => [column, converted(item.get(column))]));
+        const safe = safePolicyRow(raw);
+        readBytes += Buffer.byteLength(JSON.stringify(safe), 'utf8');
+        if (readBytes > 4 * 1024 * 1024)
+            throw new MapQueryError('MAP_LIMIT_EXCEEDED');
+        if (chargeRows)
+            read.charge(safe);
+        rows.push(safe);
+    });
+    // Sort only the bounded materialized rows. A server ORDER BY would
+    // expand malformed relationship fan-out before applying its LIMIT.
+    return sortedBySerialization(rows);
+}
+/**
+ * Reads every piece of evidence a second time, after the publication recheck: if a row, a
+ * classification or an identity-scope record changed while the read ran, the read is refused.
+ */
+export async function verifyEvidence(read) {
+    for (const checked of read.policyChecks) {
+        const rows = await readPolicyRows(read, checked.plan, checked.params, false);
+        if (JSON.stringify(rows) !== JSON.stringify(checked.rows))
+            throw new MapQueryError('MAP_UNAVAILABLE');
+        const refreshed = policyEvidence(checked.plan, rows, read.now(), checked.maximumAge);
+        if (JSON.stringify(refreshed) !== JSON.stringify(checked.projection.policyEvidence ?? []))
+            throw new MapQueryError('MAP_UNAVAILABLE');
+        const scopeRows = await readScopeRows(read, checked.scopePlan, checked.params, false);
+        if (JSON.stringify(scopeRows) !== JSON.stringify(checked.scopeRows))
+            throw new MapQueryError('MAP_UNAVAILABLE');
+        const scoped = boundedRecords(identityScopeEvidence(checked.scopePlan, scopeRows, read.now(), checked.maximumAge, checked.readable), checked.scopeBudget);
+        if (JSON.stringify(scoped) !==
+            JSON.stringify(checked.projection.identityScope ?? checked.projection.identityReach ?? []))
+            throw new MapQueryError('MAP_UNAVAILABLE');
+    }
+}

package/dist/store/identity-scope.d.ts

@@ -0,0 +1,9 @@
+import { type MapSource } from '../types.js';
+import { StoreRead } from './read.js';
+/**
+ * Identity scope, once each projection holds its ancestors. A one-agent read lists every bucket
+ * per identity; an outside-guard read (list_resources, get_resource_access) asks only about the
+ * buckets visible bindings map to. It is optional evidence throughout: whatever cannot be
+ * planned, read or fitted is left out, and the read answers without it.
+ */
+export declare function loadIdentityScope(read: StoreRead, sources: MapSource[]): Promise<void>;

package/dist/store/identity-scope.js

@@ -0,0 +1,71 @@
+import { identityScopeEvidence, identityScopePlan } from '../policy-reader.js';
+import { MapQueryError } from '../types.js';
+import { readScopeRows } from './evidence.js';
+import { boundBuckets, boundedRecords, SCOPE_HEADROOM_BYTES, SCOPE_RECORD_BYTES } from './nodes.js';
+import { StoreRead } from './read.js';
+/**
+ * Identity scope, once each projection holds its ancestors. A one-agent read lists every bucket
+ * per identity; an outside-guard read (list_resources, get_resource_access) asks only about the
+ * buckets visible bindings map to. It is optional evidence throughout: whatever cannot be
+ * planned, read or fitted is left out, and the read answers without it.
+ */
+export async function loadIdentityScope(read, sources) {
+    const { scope } = read;
+    for (const job of read.scopeJobs) {
+        const index = sources.findIndex(item => item.id === job.sourceId);
+        const current = sources[index].current;
+        const buckets = boundBuckets(current.nodes);
+        // Identity scope is optional evidence: if planning it needs more work than allowed,
+        // the read goes on without it (records read unknown, reach cannot be none_found).
+        let scopePlan;
+        try {
+            scopePlan = !job.reach
+                ? // Each distinct identity can return about 1,500 candidates; eight keeps a broad
+                    // fleet inside the read's byte budget, and the rest report not_evaluated.
+                    identityScopePlan(scope.companyId, sources[index].tenantId, current.nodes, current.edges, Math.max(0, 8 - read.scopePairCount), null, Date.parse(current.generatedAt))
+                : buckets.length
+                    ? identityScopePlan(scope.companyId, sources[index].tenantId, current.nodes, current.edges, Math.max(0, 32 - read.scopePairCount), buckets, Date.parse(current.generatedAt))
+                    : identityScopePlan(scope.companyId, sources[index].tenantId, [], [], 0);
+        }
+        catch (error) {
+            if (!(error instanceof MapQueryError) || error.code !== 'MAP_LIMIT_EXCEEDED')
+                throw error;
+            continue;
+        }
+        read.scopePairCount += scopePlan.probes.length;
+        // Scope rows have their own byte bound in readScope; only the bounded records count
+        // toward the view, so a broad role cannot crowd out the rest. A scope-only read with
+        // an unreadable age bound, or a malformed row fan-out, also goes on without it.
+        let scopeRows;
+        try {
+            if (scopePlan.probes.length && !job.check.plan.probes.length)
+                job.check.maximumAge = read.maximumAgeFor(job.enrolled);
+            scopeRows = await readScopeRows(read, scopePlan, job.check.params, false);
+        }
+        catch (error) {
+            if (!(error instanceof MapQueryError) ||
+                !['MAP_LIMIT_EXCEEDED', 'MAP_UNAVAILABLE'].includes(error.code) ||
+                !read.transactionOpen())
+                throw error;
+            continue;
+        }
+        // The lists are optional detail: they get what is left of the read's byte budget,
+        // less headroom for the final copy. If even the bare records do not fit, the read
+        // answers without identity scope.
+        const scopeBudget = Math.max(0, Math.min(SCOPE_RECORD_BYTES, read.limits.bytes - SCOPE_HEADROOM_BYTES - read.materializedBytes));
+        const identityScope = boundedRecords(identityScopeEvidence(scopePlan, scopeRows, read.now(), job.check.maximumAge, job.check.readable), scopeBudget);
+        if (Buffer.byteLength(JSON.stringify(identityScope), 'utf8') > scopeBudget)
+            continue;
+        for (const item of identityScope)
+            read.charge(item);
+        const updated = {
+            ...current,
+            ...(job.reach ? { identityReach: identityScope } : { identityScope }),
+        };
+        sources[index] = { ...sources[index], current: updated };
+        job.check.scopePlan = scopePlan;
+        job.check.scopeRows = scopeRows;
+        job.check.scopeBudget = scopeBudget;
+        job.check.projection = updated;
+    }
+}

package/dist/store/nodes.d.ts

@@ -0,0 +1,24 @@
+import { type JsonObject, type MapCoverage, type MapIdentityScope, type MapNode } from '../types.js';
+export declare const SCOPE_RECORD_BYTES: number;
+export declare const SCOPE_HEADROOM_BYTES: number;
+/**
+ * A stable order for bounded, already materialized rows. Each row is serialized once: the
+ * comparator would otherwise re-serialize rows of up to 1 MiB on every comparison.
+ */
+export declare function sortedBySerialization(rows: JsonObject[]): JsonObject[];
+/**
+ * Tools sharing a role each list their own extras. Past the budget (1 MiB, or what is left of
+ * the read's byte budget if that is less), keep every record but drop the lists and report
+ * them truncated, rather than fail the read.
+ */
+export declare function boundedRecords(records: readonly MapIdentityScope[], budget?: number): readonly MapIdentityScope[];
+/** Stands in for a scope row that could not be kept; the classifier reads it as truncated. */
+export declare const oversized: (key: unknown) => JsonObject;
+/** S3 bucket names that visible host bindings map to; the outside-guard reach asks only about these. */
+export declare function boundBuckets(nodes: readonly MapNode[]): string[];
+export declare function text(value: unknown): string;
+export declare function converted(value: unknown): unknown;
+export declare function safeNode(raw: unknown, label: unknown, sourceId: string, projectionId: string): MapNode;
+export declare function observationTime(value: unknown): number | undefined;
+export declare function coreCaptureTimes(raw: unknown): Partial<Record<'tasks' | 'tools', string>>;
+export declare function coverage(nodes: readonly MapNode[], captures: Partial<Record<'tasks' | 'tools', string>>, profile: string, summary: boolean, now: number): MapCoverage;