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

package/dist/service/schemas.js

@@ -0,0 +1,192 @@
+import {} from '@shieldaai/agent-guard';
+import { immutableJson } from '@shieldaai/agent-guard/internal';
+import { fail } from '../common.js';
+import { mapIdentifier } from '../types.js';
+export const MAP_OPERATIONS = [
+    'list_agents',
+    'get_agent_access',
+    'explain_access',
+    'find_agents_with_access',
+    'get_changes',
+    'get_inventory_health',
+    'list_owners',
+    'list_resources',
+    'get_resource_access',
+    'get_agent_inventory',
+    'list_undeclared_activity',
+    'list_unclaimed_identities',
+];
+/** What each operation answers, in one sentence. Shown to MCP clients as the tool description. */
+export const MAP_OPERATION_DESCRIPTIONS = Object.freeze({
+    list_agents: 'Lists the declared agents you may see, with owner, team, lifecycle and environments; filter by text, owner, team, environment, ownership, lifecycle or the dangerous-three boundary flag.',
+    get_agent_access: "Shows one agent's tasks, declared grants, bindings, MCP connections, IAM policy evidence, boundary flags and access outside the guard, with a graph of that neighborhood when it is small enough to draw. An empty policy list whose policyCoverage status is unknown was not evaluated; it does not mean no policy applies.",
+    explain_access: 'Explains, for one task, tool and resource selector, which declared grants match, which known blockers apply and which checks remain unknown; it never states that access is allowed.',
+    find_agents_with_access: 'Finds the agents whose declared grants and host bindings map to one exact resource reference or ARN for one cloud action; the results are candidates, not effective permissions.',
+    get_changes: "Compares a source's current snapshot with its previous retained one and lists what was added, removed or changed, optionally for one agent, one resource or one kind of change.",
+    get_inventory_health: 'Reports, for each source you may see, when each part of the inventory was captured, whether it is stale, how complete it is and how much activity no declared agent accounts for.',
+    list_owners: 'Lists the owners and teams that hosts name, with how many visible agents and resources each one owns.',
+    list_resources: 'Lists host-bound resources with their owner, sensitivity and scope, and whether something can reach each one outside the guard.',
+    get_resource_access: 'Shows one host-bound resource, the agents with a declared grant mapped to it, and the declared direct paths and tool identities that reach it outside the guard.',
+    get_agent_inventory: "Returns one page of one section of an agent's inventory (deployments, tasks, permissions, resources, connections, credentials, relationships, tools, bindings, identities or policies) with the size of every section. A size or total of null means that section was not evaluated, not that it is empty.",
+    list_undeclared_activity: 'Lists tasks or caller principals that ran through an enrolled executor but belong to no declared agent; it answers only for readers with all-teams visibility.',
+    list_unclaimed_identities: 'Lists IAM roles and users in enrolled AWS accounts that no declared agent names, as candidates to review; it answers only for readers with all-teams visibility.',
+});
+/** A parameter schema with the sentence MCP clients show for it. */
+const described = (definition, description) => ({
+    ...definition,
+    description,
+});
+const idSchema = { type: 'string', minLength: 1, maxLength: 4096 };
+const searchSchema = { type: 'string', maxLength: 256 };
+const limitSchema = { type: 'integer', minimum: 1, maximum: 100 };
+const offsetSchema = { type: 'integer', minimum: 0, maximum: 100_000 };
+const choice = (...values) => ({ type: 'string', enum: values });
+const limit = (rows) => described(limitSchema, `The most ${rows} to return, 1 to 100 (default 50).`);
+const offset = (rows) => described(offsetSchema, `How many ${rows} to skip, for paging (default 0).`);
+const source = (purpose) => described(idSchema, `${purpose} Use the \`id\` of a source from get_inventory_health, or an agent's \`sourceId\`.`);
+const agent = (purpose) => described(idSchema, `${purpose} Use the agent's \`id\` or its declared \`agentId\` from list_agents.`);
+export const sections = [
+    'overview',
+    'owners',
+    'deployments',
+    'tasks',
+    'permissions',
+    'resources',
+    'connections',
+    'credentials',
+    'relationships',
+    'tools',
+    'bindings',
+    'identities',
+    'policies',
+];
+const schema = (properties, required = []) => immutableJson({ type: 'object', additionalProperties: false, properties, required });
+export const MAP_INPUT_SCHEMAS = Object.freeze({
+    list_agents: schema({
+        search: described(searchSchema, 'Keep agents whose name or agent ID contains this text, ignoring case.'),
+        sourceId: source('Keep agents of this source only.'),
+        ownerId: described(idSchema, 'Keep agents whose declared owner has exactly this owner ID.'),
+        teamId: described(idSchema, 'Keep agents of exactly this team ID.'),
+        environment: described(idSchema, 'Keep agents with a deployment in exactly this environment.'),
+        ownershipStatus: described(choice('assigned', 'unassigned', 'unknown'), 'Keep agents whose ownership is assigned, unassigned or unknown.'),
+        lifecycleState: described(choice('active', 'inactive', 'retired', 'unknown'), 'Keep agents in this declared lifecycle state.'),
+        flag: described(choice('dangerous_three'), 'Keep only agents that carry this boundary flag with status exposed, mitigated or unknown.'),
+        flagStatus: described(choice('exposed', 'mitigated', 'unknown', 'absent'), 'Keep only agents whose dangerous-three flag has this status; `absent` cannot be combined with `flag`.'),
+        includeFlags: described({ type: 'boolean' }, 'Add the dangerous-three status to every returned agent. It reads tasks, so it costs more than the plain list.'),
+        limit: limit('agents'),
+        offset: offset('agents'),
+    }),
+    get_agent_access: schema({ sourceId: source('The source that holds the agent.'), agentId: agent('The agent to show.') }, ['sourceId', 'agentId']),
+    explain_access: schema({
+        sourceId: source('The source that holds the task.'),
+        taskId: described(idSchema, "The task to explain. Use its `id` or its `taskId` from an agent's tasks."),
+        tool: described(idSchema, 'The exact tool name, as written in the declared grant.'),
+        resourceId: described(idSchema, 'The exact resource selector, as written in the declared grant (a selector, not an ARN).'),
+    }, ['sourceId', 'taskId', 'tool', 'resourceId']),
+    find_agents_with_access: schema({
+        resourceRef: described(idSchema, 'The exact resource reference of a host binding, or the exact ARN that binding maps to.'),
+        action: described({ type: 'string', minLength: 3, maxLength: 256, pattern: '^[a-z0-9][a-z0-9-]*:[A-Za-z][A-Za-z0-9]*$' }, 'The cloud action in `service:Action` form, for example `s3:GetObject`.'),
+        sourceId: source('Search this source only.'),
+        limit: limit('candidate agents'),
+    }, ['resourceRef', 'action']),
+    get_changes: schema({
+        sourceId: source('The source whose snapshots to compare.'),
+        since: described(idSchema, 'The snapshot to compare from: `previous` (the default), or the id or snapshot id of the current or previous snapshot.'),
+        agentId: agent('Keep only changes that affect this agent.'),
+        resourceId: described(idSchema, 'Keep only changes that touch this resource binding. Use its `id` or `bindingId` from list_resources.'),
+        changeKind: described(choice('all', 'permissions', 'ownership', 'bindings', 'outside_guard', 'inventory'), 'Keep only changes of this kind; `all` (the default) keeps every change.'),
+        offset: offset('changes'),
+        limit: limit('changes'),
+    }, ['sourceId']),
+    get_inventory_health: schema({ sourceId: source('Report this source only.') }),
+    list_owners: schema({
+        sourceId: source('Keep owners of this source only.'),
+        search: described(searchSchema, 'Keep owners whose name or owner ID contains this text, ignoring case.'),
+        kind: described(choice('person', 'team', 'service'), 'Keep owners of this kind.'),
+        offset: offset('owners'),
+        limit: limit('owners'),
+    }),
+    list_resources: schema({
+        sourceId: source('Keep resources of this source only.'),
+        search: described(searchSchema, 'Keep resources whose display name, owner ID, binding ID or resource reference contains this text, ignoring case.'),
+        ownerId: described(idSchema, 'Keep resources whose declared owner has exactly this owner ID.'),
+        sensitivity: described(choice('public', 'internal', 'confidential', 'restricted', 'unknown'), 'Keep resources with this declared sensitivity.'),
+        offset: offset('resources'),
+        limit: limit('resources'),
+    }),
+    get_resource_access: schema({
+        sourceId: source('The source that holds the resource.'),
+        resourceId: described(idSchema, 'The resource binding to show. Use its `id` or `bindingId` from list_resources.'),
+        offset: offset('connected agents'),
+        limit: limit('connected agents'),
+    }, ['sourceId', 'resourceId']),
+    get_agent_inventory: schema({
+        sourceId: source('The source that holds the agent.'),
+        agentId: agent('The agent whose inventory to read.'),
+        section: described(choice(...sections), 'The section to page through; `overview` (the default) returns one summary row.'),
+        offset: offset('rows of the section'),
+        limit: limit('rows of the section'),
+    }, ['sourceId', 'agentId']),
+    /** Tasks or caller principals of one source that no declared agent accounts for; all-teams readers. */
+    list_undeclared_activity: schema({
+        sourceId: source('The source whose activity to list.'),
+        kind: described(choice('tasks', 'principals'), 'List undeclared `tasks` (the default) or the caller `principals` behind them.'),
+        offset: offset('rows'),
+        limit: limit('rows'),
+    }, ['sourceId']),
+    /** IAM roles and users of the enrolled AWS accounts that no declared agent names; all-teams readers. */
+    list_unclaimed_identities: schema({ offset: offset('identities'), limit: limit('identities') }),
+});
+const invalid = () => fail('MAP_REQUEST_INVALID');
+const LONE_SURROGATE = /[\uD800-\uDBFF](?![\uDC00-\uDFFF])|(?<![\uD800-\uDBFF])[\uDC00-\uDFFF]/u;
+/** The arguments of one operation, copied and checked against its closed schema. */
+export function validateQueryArguments(operation, value) {
+    if (typeof operation !== 'string' || !MAP_OPERATIONS.includes(operation))
+        invalid();
+    let copied;
+    try {
+        copied = immutableJson(value, 4, 512, 64 * 1024);
+    }
+    catch {
+        return invalid();
+    }
+    if (!copied || typeof copied !== 'object' || Array.isArray(copied))
+        invalid();
+    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)))
+        invalid();
+    for (const [key, item] of Object.entries(args)) {
+        if (key === 'limit' || key === 'offset') {
+            if (typeof item !== 'number' ||
+                !Number.isSafeInteger(item) ||
+                item < (key === 'offset' ? 0 : 1) ||
+                item > (key === 'offset' ? 100_000 : 100))
+                invalid();
+        }
+        else if (properties[key].type === 'boolean') {
+            if (typeof item !== 'boolean')
+                invalid();
+        }
+        else if (key === 'search') {
+            if (typeof item !== 'string' || [...item].length > 256 || item.includes('\0') || LONE_SURROGATE.test(item))
+                invalid();
+        }
+        else {
+            mapIdentifier(item);
+            const allowed = properties[key].enum;
+            if (Array.isArray(allowed) && !allowed.includes(item))
+                invalid();
+            if (key === 'action' &&
+                (typeof item !== 'string' || item.length > 256 || !/^[a-z0-9][a-z0-9-]*:[A-Za-z][A-Za-z0-9]*$/.test(item)))
+                invalid();
+        }
+    }
+    return args;
+}
+/** The page an operation was asked for; 50 rows from the start unless the caller says otherwise. */
+export function pageArguments(args) {
+    return { offset: args.offset ?? 0, limit: args.limit ?? 50 };
+}

package/dist/service/summaries.d.ts

@@ -0,0 +1,32 @@
+import type { JsonObject, MapEdge, MapNode, MapProjection, MapSource, MapView } from '../types.js';
+import { QueryWork } from './work.js';
+export declare function hostObservation(node: MapNode): JsonObject;
+export declare function deployments(projection: MapProjection, agent: MapNode, work: QueryWork): MapNode[];
+export declare function agentSummary(source: MapSource, projection: MapProjection, agent: MapNode, work: QueryWork): JsonObject;
+export declare function taskSummary(node: MapNode): JsonObject;
+export declare function grantSummary(node: MapNode): JsonObject;
+export declare function receipt(source: MapSource, projection?: MapProjection): JsonObject;
+export declare function findSource(view: MapView, id: string): MapSource;
+export declare function findAgent(projection: MapProjection, id: string): MapNode;
+/** Keep the selected agent's neighborhood explicit; never expand through shared tools to other agents. */
+/** An agent's own nodes and the edges among them, in projection order. */
+export interface FocusedGraph {
+    nodes: MapNode[];
+    edges: MapEdge[];
+}
+export declare function focus(projection: MapProjection, agent: MapNode, work: QueryWork): FocusedGraph;
+export declare function freshness(observedAt: unknown, now: number, staleSeconds: number): JsonObject;
+export declare function changeSummary(node: MapNode): JsonObject;
+export declare const collection: Readonly<{
+    approvals: "not_collected";
+    requestTimeDecisions: "not_collected";
+    backendReceipts: "not_collected";
+    externalPolicyHistory: "not_collected";
+}>;
+/**
+ * `counts` only over a whole scoped projection (list_owners). Over one agent's neighborhood
+ * they would count that agent alone, so the agent inventory leaves them out.
+ */
+export declare function ownerSummary(source: MapSource, projection: MapProjection, node: MapNode, work: QueryWork, counts?: boolean): JsonObject;
+export declare function resourceSummary(source: MapSource, projection: MapProjection, node: MapNode, work: QueryWork): JsonObject;
+export declare function relationshipRows(projection: MapProjection, work: QueryWork): JsonObject[];

package/dist/service/summaries.js

@@ -0,0 +1,247 @@
+import { fail } from '../common.js';
+import { safeProperties } from '../projection-fields.js';
+import { jsonObject } from './json.js';
+import { ordered } from './ordering.js';
+import { connected, matching, nodeIds, number, QueryWork, string, strings, unique } from './work.js';
+export function hostObservation(node) {
+    return {
+        authorityId: string(node, 'authority_id'),
+        manifestId: string(node, 'manifest_id'),
+        manifestRevision: number(node, 'manifest_revision'),
+        observedAt: string(node, 'manifest_observed_at'),
+    };
+}
+export function deployments(projection, agent, work) {
+    return connected(projection, new Set([agent.id]), 'G_INSTANCE_OF', work, true).filter(node => node.label === 'GuardDeployment');
+}
+export 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'),
+        purpose: string(agent, 'purpose'),
+        lifecycleState: string(agent, 'lifecycle_state') ?? 'unknown',
+        ownershipStatus: string(agent, 'ownership_status') ?? 'unknown',
+        ownershipSource: string(agent, 'ownership_source'),
+        ownerName: connected(projection, new Set([agent.id]), 'G_OWNED_BY', work)
+            .filter(n => n.label === 'GuardOwner')
+            .map(n => string(n, 'name'))[0] ?? null,
+        ownershipObservedAt: string(agent, 'manifest_observed_at'),
+        ...hostObservation(agent),
+        environments: unique(items.map(item => item.environment).filter((item) => item !== null)).sort(),
+        deployments: items,
+    };
+}
+export 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'),
+        },
+    };
+}
+export function grantSummary(node) {
+    return {
+        id: node.entityId,
+        taskId: string(node, 'task_id'),
+        tool: string(node, 'tool'),
+        resources: strings(node, 'resources'),
+        evidenceKind: 'declared',
+        assessment: 'unknown',
+    };
+}
+export 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: jsonObject(projection.coverage),
+    };
+}
+export function findSource(view, id) {
+    const source = view.sources.find(item => item.id === id);
+    if (!source)
+        fail('MAP_NOT_FOUND');
+    return source;
+}
+export 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;
+}
+export 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, new Set([agent.id]), 'G_OWNED_BY', work),
+        ...connected(projection, nodeIds(resourceBindings), 'G_RESOURCE_OWNED_BY', work),
+        ...connected(projection, nodeIds(deployment), 'G_USES_CREDENTIAL', work),
+        ...connected(projection, nodeIds(deployment), 'G_DIRECT_ACCESS_FOR', work, true),
+        ...connected(projection, nodeIds(executions), 'G_USES_IDENTITY', work),
+        ...connected(projection, nodeIds(resourceBindings), 'G_MAPS_TO', work),
+    ]);
+    // Build the subgraph from the index instead of scanning the whole projection per agent:
+    // the same nodes and edges in projection order, at a cost proportional to this subgraph.
+    const index = work.index(projection), nodePositions = [], edgePositions = [];
+    for (const id of selected) {
+        nodePositions.push(...(index.nodePositions.get(id) ?? []));
+        const outgoing = index.edgesFrom.get(id) ?? [];
+        work.step(1 + outgoing.length);
+        for (const position of outgoing)
+            if (selected.has(projection.edges[position].target))
+                edgePositions.push(position);
+    }
+    nodePositions.sort((a, b) => a - b);
+    edgePositions.sort((a, b) => a - b);
+    return {
+        nodes: nodePositions.map(position => projection.nodes[position]),
+        edges: edgePositions.map(position => projection.edges[position]),
+    };
+}
+export 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,
+    };
+}
+export function changeSummary(node) {
+    return {
+        entityId: node.entityId,
+        label: node.label,
+        name: string(node, 'name') ??
+            string(node, 'display_name') ??
+            string(node, 'description') ??
+            string(node, 'task_id') ??
+            string(node, 'agent_id') ??
+            string(node, 'deployment_id') ??
+            string(node, 'binding_id') ??
+            string(node, 'connection_id') ??
+            string(node, 'resource_id') ??
+            string(node, 'tool') ??
+            node.entityId,
+    };
+}
+export const collection = Object.freeze({
+    approvals: 'not_collected',
+    requestTimeDecisions: 'not_collected',
+    backendReceipts: 'not_collected',
+    externalPolicyHistory: 'not_collected',
+});
+/**
+ * `counts` only over a whole scoped projection (list_owners). Over one agent's neighborhood
+ * they would count that agent alone, so the agent inventory leaves them out.
+ */
+export function ownerSummary(source, projection, node, work, counts = true) {
+    return {
+        id: node.entityId,
+        ownerId: string(node, 'owner_id'),
+        name: string(node, 'name'),
+        kind: string(node, 'kind'),
+        sourceId: source.id,
+        ...hostObservation(node),
+        ...(counts
+            ? {
+                agentCount: connected(projection, new Set([node.id]), 'G_OWNED_BY', work, true).filter(n => n.label === 'GuardAgent').length,
+                resourceCount: connected(projection, new Set([node.id]), 'G_RESOURCE_OWNED_BY', work, true).filter(n => n.label === 'GuardResourceBinding').length,
+            }
+            : {}),
+    };
+}
+export function resourceSummary(source, projection, node, work) {
+    return {
+        id: node.entityId,
+        bindingId: string(node, 'binding_id'),
+        sourceId: source.id,
+        displayName: string(node, 'display_name') ?? string(node, 'resource_ref'),
+        tool: string(node, 'tool'),
+        resourceRef: string(node, 'resource_ref'),
+        scope: string(node, 'scope'),
+        actions: strings(node, 'actions'),
+        ownerId: string(node, 'owner_id'),
+        ownerName: connected(projection, new Set([node.id]), 'G_RESOURCE_OWNED_BY', work)
+            .filter(n => n.label === 'GuardOwner')
+            .map(n => string(n, 'name'))[0] ?? null,
+        ownershipStatus: string(node, 'ownership_status') ?? 'unknown',
+        ownershipSource: string(node, 'ownership_source'),
+        sensitivity: string(node, 'sensitivity') ?? 'unknown',
+        approvedDestinations: strings(node, 'approved_destinations'),
+        targets: connected(projection, new Set([node.id]), 'G_MAPS_TO', work)
+            .filter(n => n.label === 'GuardExternalResource')
+            .map(n => ({ id: n.entityId, ...safeProperties(n) })),
+        dependencies: connected(projection, new Set([node.id]), 'G_DEPENDS_ON', work)
+            .filter(n => n.label === 'GuardResourceBinding')
+            .map(n => ({
+            id: n.entityId,
+            bindingId: string(n, 'binding_id'),
+            displayName: string(n, 'display_name') ?? string(n, 'resource_ref'),
+        })),
+        ...hostObservation(node),
+    };
+}
+export function relationshipRows(projection, work) {
+    const index = work.index(projection);
+    work.step(projection.edges.length);
+    return ordered(projection.edges.flatMap(edge => {
+        const source = index.nodes.get(edge.source), target = index.nodes.get(edge.target);
+        return source && target
+            ? [
+                {
+                    source: source.entityId,
+                    target: target.entityId,
+                    kind: edge.kind,
+                    sourceName: changeSummary(source).name,
+                    sourceLabel: source.label,
+                    targetName: changeSummary(target).name,
+                    targetLabel: target.label,
+                },
+            ]
+            : [];
+    }));
+}

package/dist/service/work.d.ts

@@ -0,0 +1,33 @@
+import { type GraphIndex } from '../common.js';
+import type { JsonObject, MapEdge, MapNode, MapProjection } from '../types.js';
+export declare const string: (node: MapNode, key: string) => string | null;
+export declare const number: (node: MapNode, key: string) => number | null;
+export declare const strings: (node: MapNode, key: string) => readonly string[];
+export declare const matching: (node: MapNode, id: string, native: string) => boolean;
+export declare const unique: <T>(values: readonly T[]) => T[];
+export interface ProjectionLookup {
+    /** The first tool node of each name. */
+    readonly tools: ReadonlyMap<string, MapNode>;
+    /** Resource bindings by `bindingKey(tool, resource_ref)`. */
+    readonly bindings: ReadonlyMap<string, readonly MapNode[]>;
+}
+export declare const bindingKey: (tool: string, reference: string) => string;
+/** Count authorized work and elapsed monotonic time, including synchronous projection. */
+export declare class QueryWork {
+    #private;
+    constructor(timeout: number, maxBytes: number);
+    /** Milliseconds left before this query's deadline. */
+    remaining(): number;
+    step(amount?: number): void;
+    index(projection: MapProjection): GraphIndex;
+    /** A value derived from one projection, built once per query (for example its validated policy evidence). */
+    cached<T>(projection: MapProjection, name: string, build: () => T): T;
+    evidence(value: JsonObject): JsonObject;
+    /**
+     * Tools by name and resource bindings by tool and reference, in projection order. Built once
+     * per projection, so a row of evidence costs its own lookups and not a scan of every node.
+     */
+    lookup(projection: MapProjection): ProjectionLookup;
+}
+export declare function connected(projection: MapProjection, ids: Set<string>, kind: MapEdge['kind'], work: QueryWork, reverse?: boolean): MapNode[];
+export declare const nodeIds: (nodes: readonly MapNode[]) => Set<string>;

package/dist/service/work.js

@@ -0,0 +1,116 @@
+import { Buffer } from 'node:buffer';
+import { immutableJson } from '@shieldaai/agent-guard/internal';
+import { buildGraphIndex, fail } from '../common.js';
+export const string = (node, key) => typeof node.properties[key] === 'string' ? node.properties[key] : null;
+export const number = (node, key) => typeof node.properties[key] === 'number' ? node.properties[key] : null;
+export const strings = (node, key) => Array.isArray(node.properties[key])
+    ? node.properties[key].filter((v) => typeof v === 'string')
+    : [];
+export const matching = (node, id, native) => node.entityId === id || string(node, native) === id;
+export const unique = (values) => [...new Set(values)];
+export const bindingKey = (tool, reference) => JSON.stringify([tool, reference]);
+/** Count authorized work and elapsed monotonic time, including synchronous projection. */
+export class QueryWork {
+    #deadline;
+    #indices = new WeakMap();
+    #derived = new WeakMap();
+    #lookups = new WeakMap();
+    #remaining = 200_000;
+    #evidenceBytes;
+    #evidenceCount = 0;
+    constructor(timeout, maxBytes) {
+        this.#deadline = performance.now() + timeout;
+        this.#evidenceBytes = maxBytes;
+    }
+    /** Milliseconds left before this query's deadline. */
+    remaining() {
+        return Math.max(0, this.#deadline - performance.now());
+    }
+    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 = buildGraphIndex(projection.nodes, projection.edges);
+        this.#indices.set(projection, result);
+        this.step();
+        return result;
+    }
+    /** A value derived from one projection, built once per query (for example its validated policy evidence). */
+    cached(projection, name, build) {
+        let values = this.#derived.get(projection);
+        if (!values) {
+            values = new Map();
+            this.#derived.set(projection, values);
+        }
+        if (!values.has(name))
+            values.set(name, build());
+        return values.get(name);
+    }
+    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;
+    }
+    /**
+     * Tools by name and resource bindings by tool and reference, in projection order. Built once
+     * per projection, so a row of evidence costs its own lookups and not a scan of every node.
+     */
+    lookup(projection) {
+        const existing = this.#lookups.get(projection);
+        if (existing)
+            return existing;
+        this.step(projection.nodes.length);
+        const tools = new Map(), bindings = new Map();
+        for (const node of projection.nodes) {
+            if (node.label === 'GuardTool') {
+                const name = string(node, 'name');
+                if (name !== null && !tools.has(name))
+                    tools.set(name, node);
+            }
+            else if (node.label === 'GuardResourceBinding') {
+                const tool = string(node, 'tool'), reference = string(node, 'resource_ref');
+                if (tool === null || reference === null)
+                    continue;
+                const key = bindingKey(tool, reference), items = bindings.get(key);
+                if (items)
+                    items.push(node);
+                else
+                    bindings.set(key, [node]);
+            }
+        }
+        const result = { tools, bindings };
+        this.#lookups.set(projection, result);
+        return result;
+    }
+}
+export 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)] : []));
+}
+export const nodeIds = (nodes) => new Set(nodes.map(node => node.id));

package/dist/service.d.ts

@@ -1,7 +1,8 @@
-import { type JsonObject, type JsonValue, type MapEdge, type MapNode, type MapStore, type ReadScope } from './types.js';
-export declare const MAP_OPERATIONS: readonly ['list_agents', 'get_agent_access', 'explain_access', 'find_agents_with_access', 'get_changes', 'get_inventory_health'];
-export type MapOperation = typeof MAP_OPERATIONS[number];
-export declare const MAP_INPUT_SCHEMAS: Readonly<Record<MapOperation, JsonObject>>;
+import { type JsonObject, type MapEdge, type MapNode, type MapStore, type ReadScope } from './types.js';
+import { type MapOperation } from './service/schemas.js';
+export { MAP_OPERATIONS, MAP_INPUT_SCHEMAS, MAP_OPERATION_DESCRIPTIONS, validateQueryArguments, type MapOperation, } from './service/schemas.js';
+export { MAP_LABELS, MAP_RELATIONSHIPS } from './types.js';
+export { MAP_PROPERTIES } from './projection-fields.js';
 export interface MapResponse {
     readonly operation: MapOperation;
     readonly observedAt: string;
@@ -19,7 +20,6 @@ export interface MapServiceOptions {
     readonly queryTimeoutMs?: number;
     readonly staleAfterSeconds?: number;
 }
-export declare function validateQueryArguments(operation: unknown, value: unknown): Readonly<Record<string, JsonValue>>;
 /** One read-only evidence layer shared by HTTP, MCP and the browser. */
 export declare class MapService {
     #private;