@shieldaai/agent-map 0.1.0-alpha.2 → 1.0.0

package/dist/service.js

@@ -1,499 +1,40 @@
-import { canonicalJson, immutableJson } from '@shieldaai/agent-guard';
-import { MapQueryError, mapIdentifier, validateReadScope } from './types.js';
-export const MAP_OPERATIONS = ['list_agents', 'get_agent_access', 'explain_access',
-    'find_agents_with_access', 'get_changes', 'get_inventory_health'];
-const idSchema = { type: 'string', minLength: 1, maxLength: 4096 };
-const limitSchema = { type: 'integer', minimum: 1, maximum: 100 };
-const schema = (properties, required = []) => immutableJson({ type: 'object', additionalProperties: false, properties, required });
-export const MAP_INPUT_SCHEMAS = Object.freeze({
-    list_agents: schema({ search: { type: 'string', maxLength: 256 }, sourceId: idSchema,
-        ownerId: idSchema, environment: idSchema, limit: limitSchema }),
-    get_agent_access: schema({ sourceId: idSchema, agentId: idSchema }, ['sourceId', 'agentId']),
-    explain_access: schema({ sourceId: idSchema, taskId: idSchema, tool: idSchema, resourceId: idSchema }, ['sourceId', 'taskId', 'tool', 'resourceId']),
-    find_agents_with_access: schema({ resourceRef: idSchema,
-        action: { type: 'string', minLength: 3, maxLength: 256, pattern: '^[a-z0-9][a-z0-9-]*:[A-Za-z][A-Za-z0-9]*$' },
-        sourceId: idSchema, limit: limitSchema }, ['resourceRef', 'action']),
-    get_changes: schema({ sourceId: idSchema, since: idSchema }, ['sourceId']),
-    get_inventory_health: schema({ sourceId: idSchema }),
+import { immutableJson } from '@shieldaai/agent-guard/internal';
+import { fail, integer } from './common.js';
+import { MapQueryError, validateReadScope, } from './types.js';
+import { validateQueryArguments } from './service/schemas.js';
+import { QueryWork } from './service/work.js';
+import { shortenIdentityScope } from './service/outside-guard.js';
+import { listAgents } from './service/operations/list-agents.js';
+import { getAgentAccess } from './service/operations/get-agent-access.js';
+import { explainAccess } from './service/operations/explain-access.js';
+import { findAgentsWithAccess } from './service/operations/find-agents-with-access.js';
+import { getChanges } from './service/operations/get-changes.js';
+import { getInventoryHealth } from './service/operations/get-inventory-health.js';
+import { listOwners, listResources } from './service/operations/list-owners-resources.js';
+import { getResourceAccess } from './service/operations/get-resource-access.js';
+import { getAgentInventory } from './service/operations/get-agent-inventory.js';
+import { listUnclaimedIdentities, listUndeclaredActivity } from './service/operations/discovery.js';
+export { MAP_OPERATIONS, MAP_INPUT_SCHEMAS, MAP_OPERATION_DESCRIPTIONS, validateQueryArguments, } from './service/schemas.js';
+// The closed vocabularies of the graph, for a viewer that labels every value it can be sent.
+export { MAP_LABELS, MAP_RELATIONSHIPS } from './types.js';
+export { MAP_PROPERTIES } from './projection-fields.js';
+/** One handler per operation; each lives in its own module under `service/operations`. */
+const OPERATIONS = Object.freeze({
+    list_agents: listAgents,
+    get_agent_access: getAgentAccess,
+    explain_access: explainAccess,
+    find_agents_with_access: findAgentsWithAccess,
+    get_changes: getChanges,
+    get_inventory_health: getInventoryHealth,
+    list_owners: listOwners,
+    list_resources: listResources,
+    get_resource_access: getResourceAccess,
+    get_agent_inventory: getAgentInventory,
+    list_undeclared_activity: listUndeclaredActivity,
+    list_unclaimed_identities: listUnclaimedIdentities,
 });
-function fail(code = 'MAP_REQUEST_INVALID') { throw new MapQueryError(code); }
-function integer(value, fallback, maximum, minimum = 1) {
-    const chosen = value === undefined ? fallback : value;
-    if (typeof chosen !== 'number' || !Number.isSafeInteger(chosen) || chosen < minimum || chosen > maximum)
-        fail('MAP_CONFIG_INVALID');
-    return chosen;
-}
-export function validateQueryArguments(operation, value) {
-    if (typeof operation !== 'string' || !MAP_OPERATIONS.includes(operation))
-        fail();
-    let copied;
-    try {
-        copied = immutableJson(value, 4, 512, 64 * 1024);
-    }
-    catch {
-        return fail();
-    }
-    if (!copied || typeof copied !== 'object' || Array.isArray(copied))
-        fail();
-    const args = copied;
-    const definition = MAP_INPUT_SCHEMAS[operation];
-    const properties = definition.properties;
-    const required = definition.required;
-    if (Object.keys(args).some(key => !Object.hasOwn(properties, key)) || required.some(key => !Object.hasOwn(args, key)))
-        fail();
-    for (const [key, item] of Object.entries(args)) {
-        if (key === 'limit') {
-            if (typeof item !== 'number' || !Number.isSafeInteger(item) || item < 1 || item > 100)
-                fail();
-        }
-        else if (key === 'search') {
-            if (typeof item !== 'string' || [...item].length > 256 || item.includes('\0') ||
-                /[\uD800-\uDBFF](?![\uDC00-\uDFFF])|(?<![\uD800-\uDBFF])[\uDC00-\uDFFF]/u.test(item))
-                fail();
-        }
-        else {
-            mapIdentifier(item);
-            if (key === 'action' && (typeof item !== 'string' || item.length > 256 || !/^[a-z0-9][a-z0-9-]*:[A-Za-z][A-Za-z0-9]*$/.test(item)))
-                fail();
-        }
-    }
-    return args;
-}
-const string = (node, key) => typeof node.properties[key] === 'string' ? node.properties[key] : null;
-const number = (node, key) => typeof node.properties[key] === 'number' ? node.properties[key] : null;
-const strings = (node, key) => Array.isArray(node.properties[key]) ? node.properties[key].filter((v) => typeof v === 'string') : [];
-const matching = (node, id, native) => node.entityId === id || string(node, native) === id;
-const unique = (values) => [...new Set(values)];
-/** Count authorized work and elapsed monotonic time, including synchronous projection. */
-class QueryWork {
-    #deadline;
-    #indices = new WeakMap();
-    #policy = new WeakMap();
-    #remaining = 200_000;
-    #evidenceBytes;
-    #evidenceCount = 0;
-    constructor(timeout, maxBytes) { this.#deadline = performance.now() + timeout; this.#evidenceBytes = maxBytes; }
-    step(amount = 1) {
-        if (performance.now() >= this.#deadline)
-            fail('MAP_TIMEOUT');
-        this.#remaining -= amount;
-        if (this.#remaining < 0)
-            fail('MAP_LIMIT_EXCEEDED');
-    }
-    index(projection) {
-        this.step();
-        const existing = this.#indices.get(projection);
-        if (existing)
-            return existing;
-        this.step(projection.nodes.length + projection.edges.length);
-        const result = { nodes: new Map(), outgoing: new Map(), incoming: new Map() };
-        for (const node of projection.nodes)
-            result.nodes.set(node.id, node);
-        const add = (map, from, kind, to) => {
-            let kinds = map.get(from);
-            if (!kinds) {
-                kinds = new Map();
-                map.set(from, kinds);
-            }
-            const items = kinds.get(kind);
-            if (items)
-                items.push(to);
-            else
-                kinds.set(kind, [to]);
-        };
-        for (const edge of projection.edges) {
-            add(result.outgoing, edge.source, edge.kind, edge.target);
-            add(result.incoming, edge.target, edge.kind, edge.source);
-        }
-        this.#indices.set(projection, result);
-        this.step();
-        return result;
-    }
-    evidence(value) {
-        this.step();
-        if (++this.#evidenceCount > 1000)
-            fail('MAP_LIMIT_EXCEEDED');
-        let copy;
-        try {
-            copy = immutableJson(value, 24, 25_000, this.#evidenceBytes);
-        }
-        catch {
-            return fail('MAP_LIMIT_EXCEEDED');
-        }
-        this.#evidenceBytes -= Buffer.byteLength(JSON.stringify(copy));
-        this.step();
-        return copy;
-    }
-    policy(projection) {
-        const existing = this.#policy.get(projection);
-        if (existing)
-            return existing;
-        const result = validatedPolicyEvidence(projection, this);
-        this.#policy.set(projection, result);
-        return result;
-    }
-}
-function connected(projection, ids, kind, work, reverse = false) {
-    const index = work.index(projection), selected = new Set();
-    work.step(ids.size);
-    for (const id of ids) {
-        const targets = (reverse ? index.incoming : index.outgoing).get(id)?.get(kind) ?? [];
-        work.step(targets.length);
-        for (const target of targets)
-            selected.add(target);
-    }
-    return [...selected].flatMap(id => index.nodes.get(id) ? [index.nodes.get(id)] : []);
-}
-const nodeIds = (nodes) => new Set(nodes.map(node => node.id));
-function deployments(projection, agent, work) {
-    return connected(projection, new Set([agent.id]), 'G_INSTANCE_OF', work, true).filter(node => node.label === 'GuardDeployment');
-}
-function agentSummary(source, projection, agent, work) {
-    const items = deployments(projection, agent, work).map(node => ({ id: node.entityId,
-        deploymentId: string(node, 'deployment_id'), environment: string(node, 'environment') }));
-    return { id: agent.entityId, agentId: string(agent, 'agent_id'), sourceId: source.id,
-        name: string(agent, 'name'), ownerId: string(agent, 'owner_id'), teamId: string(agent, 'team_id'),
-        environments: unique(items.map(item => item.environment).filter((item) => item !== null)).sort(),
-        deployments: items };
-}
-function taskSummary(node) {
-    return { id: node.entityId, taskId: string(node, 'task_id'), principalId: string(node, 'principal_id'),
-        revoked: node.properties.revoked ?? null, sensitive: node.properties.sensitive ?? null,
-        usage: { calls: number(node, 'calls'), concurrent: number(node, 'concurrent'), spent: number(node, 'spent'), reserved: number(node, 'reserved') },
-        budget: { maxCalls: number(node, 'max_calls'), maxConcurrent: number(node, 'max_concurrent'), maxCost: number(node, 'max_cost'), deadline: number(node, 'deadline') } };
-}
-function grantSummary(node) {
-    return { id: node.entityId, taskId: string(node, 'task_id'), tool: string(node, 'tool'),
-        resources: strings(node, 'resources'), evidenceKind: 'declared', assessment: 'unknown' };
-}
-function receipt(source, projection = source.current) {
-    return { sourceId: source.id, tenantId: source.tenantId, profile: source.profile,
-        projectionId: projection.id, snapshotId: projection.snapshotId, generatedAt: projection.generatedAt,
-        coverage: projection.coverage };
-}
-function findSource(view, id) {
-    const source = view.sources.find(item => item.id === id);
-    if (!source)
-        fail('MAP_NOT_FOUND');
-    return source;
-}
-function findAgent(projection, id) {
-    const agent = projection.nodes.find(node => node.label === 'GuardAgent' && matching(node, id, 'agent_id'));
-    if (!agent)
-        fail('MAP_NOT_FOUND');
-    return agent;
-}
-/** Keep the selected agent's neighborhood explicit; never expand through shared tools to other agents. */
-function focus(projection, agent, work) {
-    const deployment = deployments(projection, agent, work);
-    const tasks = connected(projection, nodeIds(deployment), 'G_ASSIGNED_TO', work, true);
-    const executions = connected(projection, nodeIds(deployment), 'G_EXECUTES_FOR', work, true);
-    const grants = connected(projection, nodeIds(tasks), 'G_HAS_GRANT', work);
-    const resources = connected(projection, nodeIds(grants), 'G_TARGETS', work);
-    const resourceBindings = connected(projection, nodeIds(resources), 'G_BINDS_SELECTOR', work, true);
-    const tools = [...connected(projection, nodeIds(grants), 'G_FOR_TOOL', work), ...connected(projection, nodeIds(executions), 'G_EXECUTES_TOOL', work)];
-    const connections = connected(projection, nodeIds(executions), 'G_VIA_CONNECTION', work), toolIds = nodeIds(tools);
-    const operations = connected(projection, nodeIds(connections), 'G_EXPOSES_OPERATION', work).filter(operation => connected(projection, new Set([operation.id]), 'G_OPERATION_TOOL', work).some(tool => toolIds.has(tool.id)));
-    const selected = nodeIds([agent, ...deployment, ...tasks, ...executions, ...grants, ...resources, ...resourceBindings,
-        ...tools, ...connections, ...operations, ...connected(projection, nodeIds(tasks), 'G_ACTS_AS', work),
-        ...connected(projection, nodeIds(executions), 'G_USES_IDENTITY', work), ...connected(projection, nodeIds(resourceBindings), 'G_MAPS_TO', work)]);
-    work.step(projection.nodes.length + projection.edges.length);
-    return { nodes: projection.nodes.filter(node => selected.has(node.id)),
-        edges: projection.edges.filter(edge => selected.has(edge.source) && selected.has(edge.target)) };
-}
-const POLICY_ACTIONS = Object.freeze({
-    's3:GetObject': 'CAN_READ', 's3:PutObject': 'CAN_WRITE', 's3:ListBucket': 'CAN_LIST',
-});
-const POLICY_REASONS = Object.freeze({
-    unavailable: ['binding_ambiguous', 'cloud_unresolved', 'provider_missing', 'collection_invalid',
-        'stale', 'changed', 'boundary_unresolved', 'unsupported_policy', 'evidence_invalid'],
-    not_collected: ['unsupported_action', 'identity_not_static', 'unsupported_binding',
-        'cloud_not_collected', 'collection_missing', 'disabled'],
-});
-const POLICY_FIELDS = ['taskId', 'deploymentId', 'executionBindingId', 'resourceBindingId',
-    'identityId', 'resourceId', 'action', 'status', 'reason', 'observedAt', 'assessment', 'candidates'].sort().join(',');
-function policyObject(value) {
-    return !!value && typeof value === 'object' && !Array.isArray(value);
-}
-function policyTime(value) {
-    if (typeof value !== 'string')
-        return false;
-    const instant = Date.parse(value);
-    return Number.isFinite(instant) && instant >= 0 && instant <= 253_402_300_799_999 && new Date(instant).toISOString() === value;
-}
-function comparePolicyKeys(a, b) {
-    let left = 0, right = 0;
-    while (left < a.length && right < b.length) {
-        const ac = a.codePointAt(left), bc = b.codePointAt(right);
-        if (ac !== bc)
-            return ac - bc;
-        left += ac > 0xffff ? 2 : 1;
-        right += bc > 0xffff ? 2 : 1;
-    }
-    return (a.length - left) - (b.length - right);
-}
-/** Custom stores receive the same closed output contract and binding-path checks. */
-function validatedPolicyEvidence(projection, work) {
-    const rawInput = projection.policyEvidence;
-    if (rawInput === undefined)
-        return [];
-    if (!Array.isArray(rawInput))
-        fail('MAP_UNAVAILABLE');
-    if (rawInput.length > 512)
-        fail('MAP_LIMIT_EXCEEDED');
-    let input;
-    try {
-        input = immutableJson(rawInput, 8, 100_000, 4 * 1024 * 1024);
-    }
-    catch {
-        return fail('MAP_UNAVAILABLE');
-    }
-    work.step(projection.nodes.length);
-    const entities = new Map(projection.nodes.map(node => [node.entityId, node]));
-    if (input.length && entities.size !== projection.nodes.length)
-        fail('MAP_UNAVAILABLE');
-    const seen = new Set(), result = [];
-    let materializedBytes = 0;
-    const link = (source, target, kind) => {
-        const targets = work.index(projection).outgoing.get(source.id)?.get(kind) ?? [];
-        work.step(targets.length);
-        return targets.includes(target.id);
-    };
-    const exactLink = (source, target, kind) => {
-        const targets = work.index(projection).outgoing.get(source.id)?.get(kind) ?? [];
-        work.step(targets.length);
-        return targets.length === 1 && targets[0] === target.id;
-    };
-    // Tasks may have several grants and grants several selectors, but the
-    // particular pair proving this record must not have duplicate relationships.
-    const uniqueLink = (source, target, kind) => {
-        const targets = work.index(projection).outgoing.get(source.id)?.get(kind) ?? [];
-        work.step(targets.length);
-        return targets.filter(id => id === target.id).length === 1;
-    };
-    const endpoint = (id, label) => {
-        mapIdentifier(id, 'MAP_UNAVAILABLE');
-        const node = entities.get(id);
-        if (!node || node.label !== label)
-            fail('MAP_UNAVAILABLE');
-        return node;
-    };
-    for (const raw of input) {
-        work.step();
-        if (!policyObject(raw) || Object.keys(raw).sort().join(',') !== POLICY_FIELDS ||
-            raw.assessment !== 'unknown' || typeof raw.action !== 'string' || raw.action.length > 4096 ||
-            !/^[a-z0-9][a-z0-9-]*:[A-Za-z][A-Za-z0-9]*$/.test(raw.action) ||
-            (raw.observedAt !== null && !policyTime(raw.observedAt)))
-            fail('MAP_UNAVAILABLE');
-        if (!Array.isArray(raw.candidates) || raw.candidates.length > 1)
-            fail('MAP_UNAVAILABLE');
-        if (raw.status === 'complete') {
-            if (!policyTime(raw.observedAt) || !POLICY_ACTIONS[raw.action] ||
-                raw.reason !== (raw.candidates.length ? null : 'no_candidate'))
-                fail('MAP_UNAVAILABLE');
-        }
-        else if ((raw.status !== 'unavailable' && raw.status !== 'not_collected') ||
-            !POLICY_REASONS[raw.status].includes(raw.reason) || raw.candidates.length)
-            fail('MAP_UNAVAILABLE');
-        for (const candidate of raw.candidates) {
-            if (!policyObject(candidate) || Object.keys(candidate).sort().join(',') !== 'conditionKeys,hasCondition,relationship,resourceScope' ||
-                candidate.relationship !== POLICY_ACTIONS[raw.action] || candidate.resourceScope !== 'bucket_summary' ||
-                typeof candidate.hasCondition !== 'boolean' || !Array.isArray(candidate.conditionKeys) || candidate.conditionKeys.length > 128)
-                fail('MAP_UNAVAILABLE');
-            for (const key of candidate.conditionKeys) {
-                work.step();
-                mapIdentifier(key, 'MAP_UNAVAILABLE');
-                if (Buffer.byteLength(key, 'utf8') > 256 || /[\u0000-\u001f]/.test(key))
-                    fail('MAP_UNAVAILABLE');
-            }
-            if (candidate.hasCondition !== !!candidate.conditionKeys.length ||
-                JSON.stringify(candidate.conditionKeys) !== JSON.stringify([...new Set(candidate.conditionKeys)].sort(comparePolicyKeys)))
-                fail('MAP_UNAVAILABLE');
-        }
-        const task = endpoint(raw.taskId, 'GuardTask'), deployment = endpoint(raw.deploymentId, 'GuardDeployment');
-        const execution = endpoint(raw.executionBindingId, 'GuardExecutionBinding'), resource = endpoint(raw.resourceBindingId, 'GuardResourceBinding');
-        const tool = string(execution, 'tool');
-        if (!tool || string(resource, 'tool') !== tool || !strings(resource, 'actions').includes(raw.action) ||
-            !link(task, deployment, 'G_ASSIGNED_TO') || !link(execution, deployment, 'G_EXECUTES_FOR'))
-            fail('MAP_UNAVAILABLE');
-        const tools = connected(projection, new Set([execution.id]), 'G_EXECUTES_TOOL', work).filter(node => node.label === 'GuardTool' && string(node, 'name') === tool);
-        const grants = connected(projection, new Set([task.id]), 'G_HAS_GRANT', work).filter(node => node.label === 'GuardGrant' && string(node, 'tool') === tool);
-        const selectors = connected(projection, new Set([resource.id]), 'G_BINDS_SELECTOR', work).filter(node => node.label === 'GuardResource' && string(node, 'tool') === tool && string(node, 'resource_id') === string(resource, 'resource_ref'));
-        if (!grants.some(grant => strings(grant, 'resources').includes(string(resource, 'resource_ref') ?? '') &&
-            (raw.status !== 'complete' || uniqueLink(task, grant, 'G_HAS_GRANT')) &&
-            tools.some(toolNode => (raw.status === 'complete' ? exactLink : link)(grant, toolNode, 'G_FOR_TOOL')) &&
-            selectors.some(selector => (raw.status === 'complete' ? uniqueLink : link)(grant, selector, 'G_TARGETS'))))
-            fail('MAP_UNAVAILABLE');
-        for (const [key, label, relation, owner] of [
-            ['identityId', 'GuardExternalIdentity', 'G_USES_IDENTITY', execution],
-            ['resourceId', 'GuardExternalResource', 'G_MAPS_TO', resource],
-        ]) {
-            if (raw[key] === null) {
-                if (raw.status === 'complete')
-                    fail('MAP_UNAVAILABLE');
-                continue;
-            }
-            const target = endpoint(raw[key], label);
-            if (!(raw.status === 'complete' ? exactLink(owner, target, relation) : link(owner, target, relation)))
-                fail('MAP_UNAVAILABLE');
-        }
-        if (raw.status === 'complete') {
-            const agents = connected(projection, new Set([deployment.id]), 'G_INSTANCE_OF', work).filter(node => node.label === 'GuardAgent');
-            if (agents.length !== 1 || !exactLink(deployment, agents[0], 'G_INSTANCE_OF') ||
-                string(execution, 'identity_selection') !== 'static' ||
-                !exactLink(task, deployment, 'G_ASSIGNED_TO') || !exactLink(execution, deployment, 'G_EXECUTES_FOR') ||
-                tools.length !== 1 || !exactLink(execution, tools[0], 'G_EXECUTES_TOOL') || selectors.length !== 1 ||
-                !exactLink(resource, selectors[0], 'G_BINDS_SELECTOR'))
-                fail('MAP_UNAVAILABLE');
-        }
-        const identity = JSON.stringify([raw.taskId, raw.deploymentId, raw.executionBindingId, raw.resourceBindingId, raw.action]);
-        if (seen.has(identity))
-            fail('MAP_UNAVAILABLE');
-        seen.add(identity);
-        try {
-            const copy = immutableJson(raw, 6, 1024, 64 * 1024);
-            materializedBytes += Buffer.byteLength(JSON.stringify(copy));
-            if (materializedBytes > 4 * 1024 * 1024)
-                fail('MAP_LIMIT_EXCEEDED');
-            result.push(copy);
-        }
-        catch {
-            fail('MAP_LIMIT_EXCEEDED');
-        }
-    }
-    return result;
-}
-function policyCoverage(records) {
-    const complete = records.filter(item => item.status === 'complete').length;
-    const observed = records.flatMap(item => item.observedAt === null ? [] : [item.observedAt]).sort();
-    return { status: !records.length || records.every(item => item.status === 'not_collected') ? 'not_collected' :
-            complete === records.length ? 'complete' : complete ? 'partial' : 'unavailable',
-        observedAt: observed[0] ?? null, assessment: 'unknown' };
-}
-function selectedPolicy(projection, work, options = {}) {
-    const ids = options.nodes ? new Set(options.nodes.map(node => node.entityId)) : undefined;
-    const executions = options.executions ? new Set(options.executions.map(node => node.entityId)) : undefined;
-    const resources = options.resources ? new Set(options.resources.map(node => node.entityId)) : undefined;
-    return work.policy(projection).filter(record => {
-        work.step();
-        return (!ids || [record.taskId, record.deploymentId, record.executionBindingId, record.resourceBindingId,
-            record.identityId, record.resourceId].every(id => id === null || ids.has(id))) &&
-            (!options.task || record.taskId === options.task.entityId) && (!executions || executions.has(record.executionBindingId)) &&
-            (!resources || resources.has(record.resourceBindingId)) && (!options.action || record.action === options.action);
-    });
-}
-function knownBlockers(task, tool, now) {
-    const blockers = [];
-    if (task.properties.revoked === true)
-        blockers.push('task_revoked');
-    const deadline = number(task, 'deadline');
-    if (deadline !== null && now >= deadline)
-        blockers.push('deadline_expired');
-    const calls = number(task, 'calls'), maxCalls = number(task, 'max_calls');
-    if (calls !== null && maxCalls !== null && calls >= maxCalls)
-        blockers.push('call_budget_exhausted');
-    const concurrent = number(task, 'concurrent'), maxConcurrent = number(task, 'max_concurrent');
-    if (concurrent !== null && maxConcurrent !== null && concurrent >= maxConcurrent)
-        blockers.push('concurrency_full_at_capture');
-    const spent = number(task, 'spent'), reserved = number(task, 'reserved'), maxCost = number(task, 'max_cost');
-    const cost = tool ? number(tool, 'max_cost') : null;
-    if (spent !== null && reserved !== null && maxCost !== null && cost !== null && spent + reserved + cost > maxCost)
-        blockers.push('cost_budget_exceeded');
-    if (tool?.properties.control_plane === true && task.properties.allow_control_plane === false)
-        blockers.push('control_plane_disabled');
-    return blockers;
-}
-function externalEvidence(projection, task, toolName, resourceId, work, policySelection = {}) {
-    const deployment = connected(projection, new Set([task.id]), 'G_ASSIGNED_TO', work);
-    const executions = connected(projection, nodeIds(deployment), 'G_EXECUTES_FOR', work, true)
-        .filter(node => string(node, 'tool') === toolName);
-    work.step(projection.nodes.length);
-    const resources = projection.nodes.filter(node => node.label === 'GuardResourceBinding' &&
-        string(node, 'tool') === toolName && string(node, 'resource_ref') === resourceId &&
-        (!policySelection.resourceBindingId || node.entityId === policySelection.resourceBindingId));
-    const policy = selectedPolicy(projection, work, { task, executions, resources,
-        ...(policySelection.action ? { action: policySelection.action } : {}) });
-    return {
-        executionBindings: executions.map(node => ({ id: node.entityId, ...node.properties,
-            identities: connected(projection, new Set([node.id]), 'G_USES_IDENTITY', work).map(identity => ({ ...identity.properties })),
-            connections: connected(projection, new Set([node.id]), 'G_VIA_CONNECTION', work).map(connection => ({ ...connection.properties })) })),
-        resourceBindings: resources.map(node => ({ id: node.entityId, ...node.properties,
-            targets: connected(projection, new Set([node.id]), 'G_MAPS_TO', work).map(target => ({ ...target.properties })) })),
-        policyEvidence: policy, policyCoverage: policyCoverage(policy),
-        assessment: 'unknown',
-        limitations: ['Host bindings and provider inventory are evidence, not effective cloud permissions.',
-            'Container matches do not establish exact object or prefix access; missing evidence does not establish denial.'],
-    };
-}
-const COMMON_UNKNOWN = ['live_authorization', 'request_arguments_and_resolution', 'custom_policy', 'backend_authorization', 'action_approval'];
-function explain(projection, scope, task, toolName, resourceId, now, work, policySelection = {}) {
-    const index = work.index(projection), nodes = index.nodes;
-    work.step(projection.nodes.length);
-    const tool = projection.nodes.find(node => node.label === 'GuardTool' && string(node, 'name') === toolName);
-    const blockers = [], matched = [], chain = [];
-    const unknown = [...COMMON_UNKNOWN];
-    if (!scope.allTeams)
-        unknown.push('ancestor_evidence_outside_visible_scope');
-    if (!tool || tool.properties.known_metadata === false || tool.properties.registered === false)
-        blockers.push('tool_unregistered_at_capture');
-    else if (tool.properties.registered !== true)
-        unknown.push('tool_registration');
-    if (tool?.properties.approved === false)
-        blockers.push('tool_metadata_unapproved');
-    else if (tool?.properties.approved !== true)
-        unknown.push('tool_metadata_approval');
-    const visited = new Set();
-    let current = task;
-    for (let depth = 0; current; depth++) {
-        work.step();
-        if (depth >= 16 || visited.has(current.id)) {
-            unknown.push('delegation_depth_or_cycle');
-            break;
-        }
-        visited.add(current.id);
-        chain.push({ id: current.entityId, taskId: string(current, 'task_id') });
-        blockers.push(...knownBlockers(current, tool, now));
-        const grants = connected(projection, new Set([current.id]), 'G_HAS_GRANT', work).filter(node => node.label === 'GuardGrant' && string(node, 'tool') === toolName &&
-            strings(node, 'resources').some(resource => resource === resourceId || resource === '*'));
-        if (!grants.length)
-            blockers.push(current.id === task.id ? 'declared_grant_missing' : 'ancestor_declared_grant_missing');
-        matched.push(...grants.map(grantSummary));
-        const parents = index.outgoing.get(current.id)?.get('G_DELEGATED_FROM') ?? [];
-        work.step(parents.length);
-        if (parents.length > 1) {
-            unknown.push('delegation_evidence_ambiguous');
-            break;
-        }
-        current = parents[0] ? nodes.get(parents[0]) : undefined;
-    }
-    if (task.properties.sensitive === true)
-        unknown.push('sensitive_egress_and_recipient_checks');
-    return { taskId: string(task, 'task_id'), tool: toolName, resourceId,
-        assessment: blockers.length ? 'blocked' : 'unknown', evidenceKind: 'declared_and_observed',
-        blockers: unique(blockers), unknownChecks: unique(unknown), delegation: chain, matchedGrants: matched,
-        externalEvidence: externalEvidence(projection, task, toolName, resourceId, work, policySelection),
-        limitations: ['Explanation only; no action was prepared or executed.', 'A clear exported gate does not establish effective permission.'] };
-}
-const IGNORE_DIFF = new Set(['lastupdated', 'manifest_observed_at', 'manifest_revision', 'observed_at', 'capture_observed_at', 'cloud_observed_at']);
-function nodeState(node, projection, work) {
-    const index = work.index(projection);
-    const properties = Object.fromEntries(Object.entries(node.properties).filter(([key]) => !IGNORE_DIFF.has(key)));
-    const edges = [...(index.outgoing.get(node.id)?.entries() ?? [])].flatMap(([kind, targets]) => {
-        work.step(targets.length);
-        return targets.map(target => ({ kind, target: index.nodes.get(target)?.entityId ?? null }));
-    })
-        .sort((a, b) => `${a.kind}:${a.target}`.localeCompare(`${b.kind}:${b.target}`));
-    return canonicalJson({ properties, edges });
-}
-function freshness(observedAt, now, staleSeconds) {
-    const captured = typeof observedAt === 'string' ? Date.parse(observedAt) : NaN, age = now - captured;
-    return { stale: !Number.isFinite(captured) || age < -60_000 || age > staleSeconds * 1000,
-        ageSeconds: Number.isFinite(captured) ? Math.max(0, Math.floor(age / 1000)) : null };
-}
-function changeSummary(node) {
-    return { entityId: node.entityId, label: node.label,
-        name: string(node, 'name') ?? string(node, 'task_id') ?? string(node, 'agent_id') ?? string(node, 'deployment_id') ?? string(node, 'tool') ?? string(node, 'binding_id') ?? string(node, 'connection_id') ?? node.entityId };
-}
+/** Store errors a caller may see as they are; anything else reads as unavailable. */
+const READ_ERRORS = ['MAP_NOT_FOUND', 'MAP_LIMIT_EXCEEDED', 'MAP_UNAVAILABLE', 'MAP_TIMEOUT', 'MAP_SCOPE_INVALID'];
 /** One read-only evidence layer shared by HTTP, MCP and the browser. */
 export class MapService {
     #store;
@@ -504,15 +45,38 @@ export class MapService {
     #timeout;
     #staleSeconds;
     constructor(store, options = {}) {
-        if (!store || typeof store.read !== 'function' || (options.clock !== undefined && typeof options.clock !== 'function'))
+        if (!store ||
+            typeof store.read !== 'function' ||
+            (options.clock !== undefined && typeof options.clock !== 'function'))
             fail('MAP_CONFIG_INVALID');
         this.#store = store;
         this.#clock = options.clock ?? Date.now;
-        this.#maxBytes = integer(options.maxResponseBytes, 1024 * 1024, 8 * 1024 * 1024, 128);
-        this.#maxNodes = integer(options.maxGraphNodes, 500, 2000);
-        this.#maxEdges = integer(options.maxGraphEdges, 1000, 5000);
-        this.#timeout = integer(options.queryTimeoutMs, 5000, 10_000, 10);
-        this.#staleSeconds = integer(options.staleAfterSeconds, 900, 86400);
+        this.#maxBytes = integer(options.maxResponseBytes, 1024 * 1024, 128, 8 * 1024 * 1024);
+        this.#maxNodes = integer(options.maxGraphNodes, 500, 1, 2000);
+        this.#maxEdges = integer(options.maxGraphEdges, 1000, 1, 5000);
+        this.#timeout = integer(options.queryTimeoutMs, 5000, 10, 10_000);
+        this.#staleSeconds = integer(options.staleAfterSeconds, 900, 1, 86400);
+    }
+    /** One store read under the caller's scope, bounded by `timeout`. */
+    async #read(scope, request, timeout) {
+        let timer;
+        try {
+            return await Promise.race([
+                this.#store.read(scope, request),
+                new Promise((_resolve, reject) => {
+                    timer = setTimeout(() => reject(new MapQueryError('MAP_TIMEOUT')), timeout);
+                }),
+            ]);
+        }
+        catch (error) {
+            if (error instanceof MapQueryError && READ_ERRORS.includes(error.code))
+                throw error;
+            return fail('MAP_UNAVAILABLE');
+        }
+        finally {
+            if (timer)
+                clearTimeout(timer);
+        }
     }
     async query(inputScope, inputOperation, inputArgs) {
         const scope = validateReadScope(inputScope);
@@ -528,155 +92,56 @@ export class MapService {
         }
         if (!Number.isSafeInteger(now) || now < 0 || now > 253_402_300_799_999)
             fail('MAP_UNAVAILABLE');
-        const request = { ...(args.sourceId ? { sourceId: args.sourceId } : {}),
-            ...(operation === 'list_agents' ? { summary: true } : {}),
-            ...(operation === 'get_agent_access' ? { agentId: args.agentId } : {}),
-            ...(operation === 'get_changes' ? { history: true } : {}) };
-        let timer;
-        let view;
-        try {
-            view = await Promise.race([this.#store.read(scope, request), new Promise((_resolve, reject) => {
-                    timer = setTimeout(() => reject(new MapQueryError('MAP_TIMEOUT')), this.#timeout);
-                })]);
-        }
-        catch (error) {
-            if (error instanceof MapQueryError && ['MAP_NOT_FOUND', 'MAP_LIMIT_EXCEEDED', 'MAP_UNAVAILABLE', 'MAP_TIMEOUT', 'MAP_SCOPE_INVALID'].includes(error.code))
-                throw error;
-            return fail('MAP_UNAVAILABLE');
-        }
-        finally {
-            if (timer)
-                clearTimeout(timer);
-        }
+        const handler = OPERATIONS[operation];
+        const read = (request, timeout = this.#timeout) => this.#read(scope, request, timeout);
+        const request = handler.request(args);
+        const view = request === null ? { sources: [] } : await read(request);
         work.step(view.sources.length);
-        let data;
-        let graph;
-        if (operation === 'list_agents') {
-            const search = typeof args.search === 'string' ? args.search.toLocaleLowerCase('en-US') : '';
-            const agents = view.sources.flatMap(source => {
-                work.step(source.current.nodes.length);
-                return source.current.nodes.filter(node => node.label === 'GuardAgent').map(agent => agentSummary(source, source.current, agent, work));
-            })
-                .filter(agent => (!search || [agent.name, agent.agentId].some(value => typeof value === 'string' && value.toLocaleLowerCase('en-US').includes(search))) &&
-                (args.ownerId === undefined || agent.ownerId === args.ownerId) &&
-                (args.environment === undefined || agent.environments.includes(args.environment)))
-                .sort((a, b) => `${a.name}:${a.sourceId}:${a.id}`.localeCompare(`${b.name}:${b.sourceId}:${b.id}`));
-            const limit = args.limit ?? 50;
-            data = { agents: agents.slice(0, limit), truncated: agents.length > limit };
-        }
-        else if (operation === 'get_agent_access') {
-            const source = findSource(view, args.sourceId), projection = source.current;
-            const agent = findAgent(projection, args.agentId);
-            graph = focus(projection, agent, work);
-            const policy = selectedPolicy(projection, work, { nodes: graph.nodes });
-            data = { agent: agentSummary(source, projection, agent, work),
-                deployments: graph.nodes.filter(node => node.label === 'GuardDeployment').map(node => ({ id: node.entityId, deploymentId: string(node, 'deployment_id'), environment: string(node, 'environment') })),
-                tasks: graph.nodes.filter(node => node.label === 'GuardTask').map(taskSummary),
-                grants: graph.nodes.filter(node => node.label === 'GuardGrant').map(grantSummary),
-                connections: graph.nodes.filter(node => node.label === 'GuardMcpConnection').map(node => ({ id: node.entityId, ...node.properties })),
-                bindings: graph.nodes.filter(node => ['GuardExecutionBinding', 'GuardResourceBinding'].includes(node.label)).map(node => ({ id: node.entityId, kind: node.label, ...node.properties })),
-                policyEvidence: policy, policyCoverage: policyCoverage(policy),
-                receipt: receipt(source), assessment: 'unknown',
-                limitations: ['Declared and observed evidence only; current executor admission is required.', 'External object and prefix bindings retain their original scope.'] };
+        const result = await handler.run({ scope, args, now, work, maxBytes: this.#maxBytes, staleSeconds: this.#staleSeconds, read }, view);
+        let { data, graph } = result;
+        // The focused graph is an optional picture of evidence the response already lists. Past the
+        // display cap it is left out and `graphStatus` says so; the evidence itself still answers.
+        const withoutGraph = (payload) => ({
+            ...payload,
+            graphStatus: 'too_large',
+            graphLimit: { nodes: this.#maxNodes, edges: this.#maxEdges },
+        });
+        if (graph && (graph.nodes.length > this.#maxNodes || graph.edges.length > this.#maxEdges)) {
+            graph = undefined;
+            data = withoutGraph(data);
         }
-        else if (operation === 'explain_access') {
-            const source = findSource(view, args.sourceId);
-            const task = source.current.nodes.find(node => node.label === 'GuardTask' && matching(node, args.taskId, 'task_id'));
-            if (!task)
-                fail('MAP_NOT_FOUND');
-            data = { ...explain(source.current, scope, task, args.tool, args.resourceId, now, work), receipt: receipt(source) };
-        }
-        else if (operation === 'find_agents_with_access') {
-            const candidates = [];
-            const limit = args.limit ?? 50;
-            let truncated = false;
-            candidateSearch: for (const source of view.sources)
-                for (const agent of source.current.nodes.filter(node => node.label === 'GuardAgent')) {
-                    work.step();
-                    const selected = focus(source.current, agent, work), selectedProjection = { ...source.current, ...selected };
-                    const bindings = selected.nodes.filter(node => node.label === 'GuardResourceBinding' && strings(node, 'actions').includes(args.action));
-                    const evidence = [];
-                    for (const binding of bindings) {
-                        work.step();
-                        const external = connected(selectedProjection, new Set([binding.id]), 'G_MAPS_TO', work)[0];
-                        if (string(binding, 'resource_ref') !== args.resourceRef && (!external || string(external, 'arn') !== args.resourceRef))
-                            continue;
-                        const toolName = string(binding, 'tool'), resource = string(binding, 'resource_ref');
-                        if (!toolName || !resource)
-                            continue;
-                        for (const task of selected.nodes.filter(node => node.label === 'GuardTask')) {
-                            work.step();
-                            if (!connected(selectedProjection, new Set([task.id]), 'G_HAS_GRANT', work).some(grant => string(grant, 'tool') === toolName && strings(grant, 'resources').some(item => item === '*' || item === resource)))
-                                continue;
-                            if (candidates.length >= limit) {
-                                truncated = true;
-                                break candidateSearch;
-                            }
-                            const deployment = connected(selectedProjection, new Set([task.id]), 'G_ASSIGNED_TO', work);
-                            const executions = connected(selectedProjection, nodeIds(deployment), 'G_EXECUTES_FOR', work, true).filter(node => string(node, 'tool') === toolName);
-                            const policy = selectedPolicy(source.current, work, { task, executions, resources: [binding], action: args.action });
-                            evidence.push(work.evidence({ taskId: string(task, 'task_id'), tool: toolName, resourceRef: resource, action: args.action,
-                                scope: string(binding, 'scope'), externalResource: external ? { ...external.properties } : null,
-                                executionBindings: executions.map(node => ({ id: node.entityId, ...node.properties,
-                                    identities: connected(selectedProjection, new Set([node.id]), 'G_USES_IDENTITY', work).map(identity => ({ ...identity.properties })) })),
-                                policyEvidence: policy, policyCoverage: policyCoverage(policy),
-                                explanation: explain(source.current, scope, task, toolName, resource, now, work, { action: args.action, resourceBindingId: binding.entityId }) }));
-                        }
-                    }
-                    if (evidence.length)
-                        candidates.push({ agent: agentSummary(source, source.current, agent, work), evidence,
-                            assessment: 'unknown', limitations: ['Potential access candidates; no effective permission decision.', 'Cloud containment is not exact object authorization.'] });
-                }
-            data = { candidates, truncated };
-        }
-        else if (operation === 'get_changes') {
-            const source = findSource(view, args.sourceId), current = source.current;
-            const since = args.since ?? 'previous';
-            const previous = [current.id, current.snapshotId].includes(since) ? current :
-                source.previous && (since === 'previous' || [source.previous.id, source.previous.snapshotId].includes(since)) ? source.previous : null;
-            const added = [], removed = [], changed = [];
-            if (previous) {
-                const before = new Map(previous.nodes.map(node => [node.entityId, node])), after = new Map(current.nodes.map(node => [node.entityId, node]));
-                for (const [id, node] of after) {
-                    work.step();
-                    if (!before.has(id))
-                        added.push(changeSummary(node));
-                    else if (nodeState(node, current, work) !== nodeState(before.get(id), previous, work))
-                        changed.push(changeSummary(node));
-                }
-                for (const [id, node] of before)
-                    if (!after.has(id))
-                        removed.push(changeSummary(node));
-            }
-            data = { sourceId: source.id, from: previous ? receipt(source, previous) : null, to: receipt(source),
-                changes: { added, removed, changed }, coverageGap: previous === null, policyHistory: 'not_collected',
-                limitations: ['Net changes in authorized retained snapshots only; not an invocation or intermediate-event log.',
-                    'Current IAM policy observations are separate from retained Guard snapshots; policy history is not collected.'] };
-        }
-        else {
-            data = { sources: view.sources.map(source => {
-                    work.step();
-                    return { id: source.id, sourceId: source.sourceId, tenantId: source.tenantId, profile: source.profile,
-                        generatedAt: source.current.generatedAt, snapshotId: source.current.snapshotId, projectionId: source.current.id,
-                        ...freshness(source.current.generatedAt, now, this.#staleSeconds),
-                        coverage: { ...Object.fromEntries(Object.entries(source.current.coverage).filter(([component]) => component !== 'policy').map(([component, status]) => {
-                                work.step();
-                                return [component, { ...status, ...freshness(status.observedAt, now, this.#staleSeconds) }];
-                            })), policy: policyCoverage(work.policy(source.current)) } };
-                }), visibility: scope.allTeams ? 'enrolled_sources' : 'visible_agent_sources',
-                limitations: ['Collection freshness is separate from current execution authority.'] };
-        }
-        if (graph && (graph.nodes.length > this.#maxNodes || graph.edges.length > this.#maxEdges))
-            fail('MAP_LIMIT_EXCEEDED');
         work.step();
-        const result = { operation, observedAt: new Date(now).toISOString(), data, ...(graph ? { graph } : {}) };
-        let copied;
-        try {
-            copied = immutableJson(result, 32, 100_000, this.#maxBytes);
+        const observedAt = new Date(now).toISOString();
+        const freeze = (payload) => {
+            try {
+                // The copy is the response: `operation`, `observedAt`, `data` and, when kept, `graph`.
+                return immutableJson({ operation, observedAt, data: payload, ...(graph ? { graph } : {}) }, 32, 100_000, this.#maxBytes);
+            }
+            catch {
+                return null;
+            }
+        };
+        // The identity-scope bucket lists are optional detail. If the response does not fit with
+        // them, shorten them (marked truncated) before giving up on the whole response.
+        const fitted = (payload) => {
+            let copied = freeze(payload);
+            for (const keep of [25, 5, 0]) {
+                if (copied)
+                    break;
+                const shortened = shortenIdentityScope(payload, keep);
+                if (shortened)
+                    copied = freeze(shortened);
+            }
+            return copied;
+        };
+        let copied = fitted(data);
+        // Still too large with the graph: answer with the evidence alone.
+        if (!copied && graph) {
+            graph = undefined;
+            copied = fitted(withoutGraph(data));
         }
-        catch {
+        if (!copied)
             return fail('MAP_LIMIT_EXCEEDED');
-        }
         work.step();
         return copied;
     }