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

package/dist/service/outside-guard.js

@@ -0,0 +1,313 @@
+import { s3BucketName, shortenScopeList } from '../common.js';
+import { MapQueryError, } from '../types.js';
+import { jsonList, jsonObject } from './json.js';
+import { compare, ordered } from './ordering.js';
+import { deployments } from './summaries.js';
+import { connected, number, QueryWork, string } from './work.js';
+/** A declared target names a host resource; name it only when that resource is in the reader's scope. */
+export function targetVisibility(projection, scope, work) {
+    if (scope.allTeams)
+        return () => true;
+    work.step(projection.nodes.length);
+    const visible = new Set([
+        ...projection.nodes
+            .filter(node => node.label === 'GuardExternalResource')
+            .map(node => string(node, 'host_resource_id'))
+            .filter((id) => id !== null),
+        ...(projection.inScopeTargets ?? []),
+    ]);
+    return target => visible.has(target);
+}
+/**
+ * Host-declared paths that act without the guard, per deployment in the agent's focus.
+ * Manifest v3 sets `direct_access_status`; older manifests leave it absent, which reads as
+ * `unknown` and never as `none_declared`.
+ */
+export function directAccess(projection, graph, scope, work) {
+    const visibleTarget = targetVisibility(projection, scope, work);
+    return ordered(graph.nodes
+        .filter(node => node.label === 'GuardDeployment')
+        .map(deployment => {
+        const entries = connected(projection, new Set([deployment.id]), 'G_DIRECT_ACCESS_FOR', work, true);
+        const declared = string(deployment, 'direct_access_status');
+        // An entry without the v3 status would be inconsistent; report what was found.
+        const status = entries.length ? 'found' : declared === 'none_declared' ? 'none_declared' : 'unknown';
+        return {
+            id: deployment.entityId,
+            deploymentId: string(deployment, 'deployment_id'),
+            status,
+            evidenceKind: 'declared',
+            entries: ordered(entries.map(entry => {
+                const target = string(entry, 'target_ref');
+                const targetStatus = target === null ? 'none' : visibleTarget(target) ? 'visible' : 'outside_visible_scope';
+                return {
+                    id: entry.entityId,
+                    accessId: string(entry, 'access_id'),
+                    kind: string(entry, 'kind'),
+                    targetRef: targetStatus === 'visible' ? target : null,
+                    targetStatus,
+                    description: string(entry, 'description'),
+                };
+            })),
+        };
+    }));
+}
+/** `data` with each identity-scope list cut to `keep` entries, or null if nothing would change. */
+export function shortenIdentityScope(data, keep) {
+    const outside = data.outsideGuard;
+    const records = outside?.identityScope;
+    if (!Array.isArray(records))
+        return null;
+    const shortened = records.map(record => shortenScopeList(record, keep));
+    if (shortened.every((record, index) => record === records[index]))
+        return null;
+    return { ...data, outsideGuard: { ...outside, identityScope: jsonList(shortened) } };
+}
+export const reachIndex = new WeakMap();
+/**
+ * Outside-guard reach over the whole visible projection: any declared direct path or any
+ * evaluated tool identity can touch any resource, so `none_found` needs every visible
+ * deployment to have declared its paths and every visible identity to be evaluated.
+ */
+export function outsideGuardIndex(projection, work) {
+    const existing = reachIndex.get(projection);
+    if (existing)
+        return existing;
+    work.step(projection.nodes.length);
+    let undeclaredDeployments = 0, untargetedPaths = 0, undeclaredIdentities = 0;
+    const identityAccounts = new Set();
+    const directByTarget = new Map();
+    // The tools each deployment has an execution binding for, read once per deployment.
+    const executed = new Map();
+    const executedTools = (deployment) => {
+        let tools = executed.get(deployment.id);
+        if (!tools) {
+            tools = new Set(connected(projection, new Set([deployment.id]), 'G_EXECUTES_FOR', work, true).map(item => string(item, 'tool')));
+            executed.set(deployment.id, tools);
+        }
+        return tools;
+    };
+    for (const node of projection.nodes) {
+        if (node.label === 'GuardDeployment') {
+            const status = string(node, 'direct_access_status');
+            // `found` with no entry in the read is inconsistent, so it is not a declaration either.
+            const entries = connected(projection, new Set([node.id]), 'G_DIRECT_ACCESS_FOR', work, true).length;
+            if (!(status === 'none_declared' || (status === 'found' && entries > 0)))
+                undeclaredDeployments++;
+        }
+        if (node.label === 'GuardDirectAccess') {
+            const target = string(node, 'target_ref');
+            if (target === null)
+                untargetedPaths++;
+            else {
+                const paths = directByTarget.get(target);
+                if (paths)
+                    paths.push(node);
+                else
+                    directByTarget.set(target, [node]);
+            }
+        }
+        if (node.label === 'GuardTask') {
+            // A granted tool runs under some identity on every deployment the task is assigned to;
+            // a deployment without an execution binding for it leaves that identity undeclared.
+            const granted = new Set(connected(projection, new Set([node.id]), 'G_HAS_GRANT', work).map(item => string(item, 'tool')));
+            if (granted.size) {
+                const deployments = connected(projection, new Set([node.id]), 'G_ASSIGNED_TO', work);
+                work.step(granted.size * deployments.length);
+                if (!deployments.length || deployments.some(item => [...granted].some(tool => !executedTools(item).has(tool))))
+                    undeclaredIdentities++;
+            }
+        }
+    }
+    const identitiesByBucket = new Map();
+    let identityUnknown = 0;
+    // A visible execution binding the reach read never reported on was not evaluated.
+    if (projection.identityReach !== undefined) {
+        const reported = new Set(projection.identityReach.map(record => record.executionBindingId));
+        for (const node of projection.nodes)
+            if (node.label === 'GuardExecutionBinding' && !reported.has(node.entityId))
+                identityUnknown++;
+    }
+    // A target the read cannot match may be any resource, so it counts like no target.
+    const hostIds = new Set(projection.nodes
+        .filter(node => node.label === 'GuardExternalResource')
+        .map(node => string(node, 'host_resource_id'))
+        .filter((id) => id !== null));
+    let unresolvedPaths = 0;
+    for (const [target, paths] of directByTarget)
+        if (!hostIds.has(target))
+            unresolvedPaths += paths.length;
+    for (const record of projection.identityReach ?? []) {
+        work.step(1 + record.extraResources.length);
+        // Only a complete comparison counts: any other status, or a record whose list was cut
+        // (it may reach buckets it no longer names), leaves reach unknown.
+        if (!(record.status === 'matches_grants' || record.status === 'broader_than_grants') || record.truncated)
+            identityUnknown++;
+        identityAccounts.add(record.accountId ?? null);
+        for (const extra of record.extraResources) {
+            const reached = identitiesByBucket.get(extra.bucketName);
+            if (reached)
+                reached.push({ record, extra });
+            else
+                identitiesByBucket.set(extra.bucketName, [{ record, extra }]);
+        }
+    }
+    const result = {
+        undeclaredDeployments,
+        untargetedPaths,
+        unresolvedPaths,
+        undeclaredIdentities,
+        directByTarget,
+        identitiesByBucket,
+        identityUnknown,
+        identityCollected: projection.identityReach !== undefined,
+        identityAccounts,
+    };
+    reachIndex.set(projection, result);
+    return result;
+}
+/** Entries listed per resource in get_resource_access before the list is marked truncated. */
+export const REACH_LIST_LIMIT = 100;
+/**
+ * `detail` builds the (bounded) lists for one resource; the listing only needs the status,
+ * which comes from index lookups.
+ */
+export function outsideGuardReach(projection, resource, scope, work, detail = false) {
+    const index = outsideGuardIndex(projection, work);
+    const targets = connected(projection, new Set([resource.id]), 'G_MAPS_TO', work);
+    // The collector writes one target per binding; anything else is malformed and never none_found.
+    const malformed = targets.length !== 1;
+    const hosts = targets.map(node => string(node, 'host_resource_id')).filter((id) => id !== null);
+    const accounts = new Set(targets.filter(node => string(node, 'provider') === 'aws').map(node => string(node, 'account_id')));
+    const buckets = targets
+        .filter(node => string(node, 'provider') === 'aws')
+        .map(node => s3BucketName(string(node, 'arn')))
+        .filter((name) => name !== null);
+    work.step(1 + hosts.length + buckets.length);
+    const reached = hosts.some(id => index.directByTarget.has(id)) || buckets.some(name => index.identitiesByBucket.has(name));
+    let directAccess = [], identities = [], directAccessTruncated = false, identitiesTruncated = false;
+    if (detail) {
+        const paths = hosts
+            .flatMap(id => index.directByTarget.get(id) ?? [])
+            .sort((a, b) => compare(a.entityId, b.entityId));
+        const reaching = buckets
+            .flatMap(name => index.identitiesByBucket.get(name) ?? [])
+            .sort((a, b) => compare(a.record.executionBindingId, b.record.executionBindingId) ||
+            compare(a.extra.bucketName, b.extra.bucketName) ||
+            compare(a.extra.relationship, b.extra.relationship));
+        work.step(paths.length + reaching.length);
+        directAccessTruncated = paths.length > REACH_LIST_LIMIT;
+        identitiesTruncated = reaching.length > REACH_LIST_LIMIT;
+        directAccess = paths.slice(0, REACH_LIST_LIMIT).map(node => ({
+            id: node.entityId,
+            accessId: string(node, 'access_id'),
+            deploymentId: string(node, 'deployment_id'),
+            kind: string(node, 'kind'),
+            description: string(node, 'description'),
+            evidenceKind: 'declared',
+        }));
+        identities = reaching.slice(0, REACH_LIST_LIMIT).map(({ record, extra }) => jsonObject({
+            id: record.executionBindingId,
+            executionBindingId: record.executionBindingId,
+            deploymentId: record.deploymentId,
+            tool: record.tool,
+            identityId: record.identityId,
+            relationship: extra.relationship,
+            hasCondition: extra.hasCondition,
+            conditionKeys: extra.conditionKeys,
+            evidenceKind: 'iam_identity_policy_candidate',
+        }));
+    }
+    const unknownReasons = [];
+    if (malformed)
+        unknownReasons.push('binding_ambiguous');
+    // Candidates exist only for buckets the AWS collection observed; an unresolved bucket was
+    // never compared with any identity.
+    if (targets.some(node => string(node, 'provider') === 'aws' && string(node, 'cloud_status') !== 'resolved'))
+        unknownReasons.push('resource_not_collected');
+    if (index.undeclaredDeployments)
+        unknownReasons.push('direct_access_undeclared');
+    if (index.untargetedPaths)
+        unknownReasons.push('direct_access_untargeted');
+    if (index.unresolvedPaths)
+        unknownReasons.push('direct_access_target_unresolved');
+    if (!buckets.length)
+        unknownReasons.push('identity_scope_not_collected_for_resource');
+    else if (!index.identityCollected)
+        unknownReasons.push('identity_scope_not_collected');
+    else {
+        if (index.identityUnknown)
+            unknownReasons.push('identity_scope_unknown');
+        // Candidates are collected per account: an identity elsewhere was never compared with
+        // this bucket, and a cross-account bucket policy can still let it in.
+        if ([...index.identityAccounts].some(account => account === null || !accounts.has(account)) || accounts.has(null))
+            unknownReasons.push('identity_scope_other_account');
+        if (index.undeclaredIdentities)
+            unknownReasons.push('execution_identity_undeclared');
+    }
+    // Paths and identities of teams this reader cannot see may reach the resource too.
+    if (!scope.allTeams && projection.outsideVisibleScope !== false)
+        unknownReasons.push('outside_visible_scope');
+    const status = reached ? 'yes' : unknownReasons.length ? 'unknown' : 'none_found';
+    return { status, unknownReasons, directAccess, directAccessTruncated, identities, identitiesTruncated };
+}
+/**
+ * Reach with its own work budget, shared by every row of one response: if it runs out, that
+ * row and every later one read `unknown` (`reach_not_evaluated`) and the response still
+ * answers. Rows judged before that keep their status: each used a complete index.
+ */
+export function boundedReach(remaining, maxBytes) {
+    const work = new QueryWork(Math.max(1, remaining - 25), maxBytes);
+    let exhausted = false;
+    return (projection, resource, scope, detail = false) => {
+        if (!exhausted)
+            try {
+                return outsideGuardReach(projection, resource, scope, work, detail);
+            }
+            catch (error) {
+                const code = error instanceof MapQueryError ? error.code : '';
+                if (code !== 'MAP_LIMIT_EXCEEDED' && code !== 'MAP_TIMEOUT')
+                    throw error;
+                exhausted = true;
+            }
+        return {
+            status: 'unknown',
+            unknownReasons: ['reach_not_evaluated'],
+            directAccess: [],
+            directAccessTruncated: false,
+            identities: [],
+            identitiesTruncated: false,
+        };
+    };
+}
+export const OUTSIDE_GUARD_LIMITATION = 'Only S3 identity policies and host declarations of this source are checked, within your visible scope; none_found is not proof that no path exists.';
+/**
+ * C2 per execution binding in the agent's focus. A store that did not run the reverse identity
+ * read reports every binding as `unknown` rather than leaving it out.
+ */
+export function identityScope(projection, graph) {
+    const executions = graph.nodes.filter(node => node.label === 'GuardExecutionBinding');
+    const known = new Map((projection.identityScope ?? []).map(item => [item.executionBindingId, item]));
+    return ordered(executions.map(execution => {
+        const item = known.get(execution.entityId);
+        return jsonObject({
+            id: execution.entityId,
+            ...(item ?? {
+                executionBindingId: execution.entityId,
+                deploymentId: null,
+                tool: string(execution, 'tool'),
+                identityId: null,
+                accountId: null,
+                status: 'unknown',
+                // The store did not evaluate this binding (not run, or more work than allowed).
+                reason: 'not_evaluated',
+                observedAt: null,
+                boundBuckets: [],
+                extraResources: [],
+                truncated: false,
+                evidenceKind: 'iam_identity_policy_candidate',
+                assessment: 'unknown',
+            }),
+        });
+    }));
+}

package/dist/service/policy.d.ts

@@ -0,0 +1,26 @@
+import { type JsonObject, type MapNode, type MapPolicyEvidence, type MapProjection } from '../types.js';
+import { QueryWork } from './work.js';
+export declare const POLICY_ACTIONS: Readonly<Record<string, string>>;
+export declare const POLICY_REASONS: Readonly<{
+    unavailable: string[];
+    not_collected: string[];
+}>;
+export declare const POLICY_FIELDS: string;
+export declare function policyObject(value: unknown): value is Record<string, unknown>;
+export declare function policyTime(value: unknown): boolean;
+export declare function policyCoverage(records: readonly MapPolicyEvidence[]): JsonObject;
+/**
+ * Coverage for a selection of one projection's policy evidence. When the store found more
+ * task/binding/action pairs than one read evaluates it loaded none: that is unknown, never
+ * "not collected".
+ */
+export declare function policyCoverageOf(projection: MapProjection, records: readonly MapPolicyEvidence[]): JsonObject;
+export declare function selectedPolicy(projection: MapProjection, work: QueryWork, options?: {
+    nodes?: readonly MapNode[];
+    task?: MapNode;
+    executions?: readonly MapNode[];
+    resources?: readonly MapNode[];
+    action?: string;
+}): readonly MapPolicyEvidence[];
+/** The projection's policy evidence, validated once per query. */
+export declare function policyRecords(projection: MapProjection, work: QueryWork): readonly MapPolicyEvidence[];

package/dist/service/policy.js

@@ -0,0 +1,299 @@
+import { Buffer } from 'node:buffer';
+import { immutableJson } from '@shieldaai/agent-guard/internal';
+import { compareCodePoints, fail } from '../common.js';
+import { mapIdentifier, } from '../types.js';
+import { connected, QueryWork, string, strings } from './work.js';
+export const POLICY_ACTIONS = Object.freeze({
+    's3:GetObject': 'CAN_READ',
+    's3:PutObject': 'CAN_WRITE',
+    's3:ListBucket': 'CAN_LIST',
+});
+export 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',
+    ],
+});
+export const POLICY_FIELDS = [
+    'taskId',
+    'deploymentId',
+    'executionBindingId',
+    'resourceBindingId',
+    'identityId',
+    'resourceId',
+    'action',
+    'status',
+    'reason',
+    'observedAt',
+    'assessment',
+    'candidates',
+]
+    .sort()
+    .join(',');
+export function policyObject(value) {
+    return !!value && typeof value === 'object' && !Array.isArray(value);
+}
+export 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);
+}
+/**
+ * A copy made by `immutableJson` is plain JSON; the checks in `validatedPolicyEvidence` are what
+ * establish that each entry has the record's shape, so nothing reads a field before they run.
+ */
+const policyList = (copy) => copy;
+/** 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 = policyList(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.observedAt !== null && !policyTime(raw.observedAt)))
+            fail('MAP_UNAVAILABLE');
+        mapIdentifier(raw.action, 'MAP_UNAVAILABLE');
+        // Generic host actions carry no cloud-policy inference. Keep their explicit
+        // unsupported observation readable without admitting a cloud candidate.
+        const genericAction = !/^[a-z0-9][a-z0-9-]*:[A-Za-z][A-Za-z0-9]*$/.test(raw.action);
+        if (genericAction) {
+            if (raw.status !== 'not_collected' || raw.reason !== 'unsupported_action')
+                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(compareCodePoints)))
+                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 (genericAction &&
+            (raw.resourceId === null || string(endpoint(raw.resourceId, 'GuardExternalResource'), 'provider') !== 'host'))
+            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 = policyList([immutableJson(raw, 6, 1024, 64 * 1024)])[0];
+            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;
+}
+export 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',
+    };
+}
+/**
+ * Coverage for a selection of one projection's policy evidence. When the store found more
+ * task/binding/action pairs than one read evaluates it loaded none: that is unknown, never
+ * "not collected".
+ */
+export function policyCoverageOf(projection, records) {
+    return projection.policyEvidenceNotLoaded === true
+        ? { status: 'unknown', reason: 'limit_exceeded', observedAt: null, assessment: 'unknown' }
+        : policyCoverage(records);
+}
+export 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;
+    const records = options.task
+        ? policyRecordsOfTask(projection, options.task.entityId, work)
+        : policyRecords(projection, work);
+    return records.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));
+    });
+}
+/** The projection's policy evidence, validated once per query. */
+export function policyRecords(projection, work) {
+    return work.cached(projection, 'policy', () => validatedPolicyEvidence(projection, work));
+}
+/** Validated policy records of one task, in their original order; indexed once per projection. */
+function policyRecordsOfTask(projection, taskEntityId, work) {
+    const index = work.cached(projection, 'policyByTask', () => {
+        const records = policyRecords(projection, work);
+        work.step(records.length);
+        const byTask = new Map();
+        for (const record of records) {
+            const items = byTask.get(record.taskId);
+            if (items)
+                items.push(record);
+            else
+                byTask.set(record.taskId, [record]);
+        }
+        return byTask;
+    });
+    return index.get(taskEntityId) ?? [];
+}

package/dist/service/schemas.d.ts

@@ -0,0 +1,16 @@
+import { type JsonObject, type JsonValue } 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', 'list_owners', 'list_resources', 'get_resource_access', 'get_agent_inventory', 'list_undeclared_activity', 'list_unclaimed_identities'];
+export type MapOperation = (typeof MAP_OPERATIONS)[number];
+export type QueryArguments = Readonly<Record<string, JsonValue>>;
+/** What each operation answers, in one sentence. Shown to MCP clients as the tool description. */
+export declare const MAP_OPERATION_DESCRIPTIONS: Readonly<Record<MapOperation, string>>;
+export declare const sections: readonly ['overview', 'owners', 'deployments', 'tasks', 'permissions', 'resources', 'connections', 'credentials', 'relationships', 'tools', 'bindings', 'identities', 'policies'];
+export type InventorySection = (typeof sections)[number];
+export declare const MAP_INPUT_SCHEMAS: Readonly<Record<MapOperation, JsonObject>>;
+/** The arguments of one operation, copied and checked against its closed schema. */
+export declare function validateQueryArguments(operation: unknown, value: unknown): QueryArguments;
+/** The page an operation was asked for; 50 rows from the start unless the caller says otherwise. */
+export declare function pageArguments(args: QueryArguments): {
+    offset: number;
+    limit: number;
+};