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

package/dist/projection-fields.d.ts

@@ -0,0 +1,4 @@
+import type { GuardLabel, JsonObject, MapNode } from './types.js';
+export declare const MAP_PROPERTIES: Readonly<Record<GuardLabel, readonly string[]>>;
+/** Defense in depth for summaries/diffs, including host-provided MapStore adapters. */
+export declare function safeProperties(node: MapNode): JsonObject;

package/dist/projection-fields.js

@@ -0,0 +1,144 @@
+const CLOUD_FIELDS = [
+    'cloud_status',
+    'cloud_reason',
+    'cloud_observed_at',
+    'cloud_assessment',
+    'cloud_provider_label',
+    'cloud_provider_id',
+    'cloud_match_kind',
+    'cloud_node_updated',
+    'cloud_ownership_updated',
+    'cloud_account_updated',
+];
+const HOST_FIELDS = [
+    'evidence_kind',
+    'assessment',
+    'manifest_id',
+    'manifest_revision',
+    'manifest_observed_at',
+    'authority_id',
+    'manifest_schema_version',
+];
+export const MAP_PROPERTIES = Object.freeze({
+    GuardAgent: [
+        'agent_id',
+        'name',
+        'owner_id',
+        'team_id',
+        'purpose',
+        'lifecycle_state',
+        'ownership_status',
+        'ownership_source',
+        ...HOST_FIELDS,
+    ],
+    GuardDeployment: [
+        'deployment_id',
+        'environment',
+        'runtime_ref',
+        'workload_generation',
+        'build_ref',
+        'binding_authority',
+        // Manifest v3 only: 'found' | 'none_declared'; absent means unknown.
+        'direct_access_status',
+        ...HOST_FIELDS,
+    ],
+    GuardTask: [
+        'task_id',
+        'principal_id',
+        'revoked',
+        'delegated',
+        'derived',
+        'sensitive',
+        'untrusted',
+        'allowed_recipients',
+        'allow_control_plane',
+        'max_calls',
+        'max_concurrent',
+        'max_cost',
+        'deadline',
+        'calls',
+        'concurrent',
+        'spent',
+        'reserved',
+    ],
+    GuardPrincipal: ['principal_id'],
+    GuardGrant: ['task_id', 'tool', 'resources', 'evidence_kind', 'assessment'],
+    GuardTool: [
+        'name',
+        'fingerprint',
+        'revision',
+        'registered',
+        'approved',
+        'known_metadata',
+        'requires_approval',
+        'control_plane',
+        'max_cost',
+        // Inventory v2 outside-content labels and the executor default; absent for v1.
+        'reads_untrusted',
+        'untrusted_context',
+        'sends_external',
+        'untrusted_context_default',
+    ],
+    GuardResource: ['resource_id', 'tool', 'selector_kind'],
+    GuardResourceBinding: [
+        'binding_id',
+        'tool',
+        'resource_ref',
+        'actions',
+        'scope',
+        'display_name',
+        'owner_id',
+        'ownership_status',
+        'ownership_source',
+        'sensitivity',
+        'approved_destinations',
+        ...HOST_FIELDS,
+    ],
+    GuardExecutionBinding: ['binding_id', 'tool', 'connection_id', 'identity_selection', ...HOST_FIELDS],
+    GuardExternalResource: [
+        'provider',
+        'partition',
+        'account_id',
+        'region',
+        'arn',
+        'kind',
+        'host_resource_id',
+        'name',
+        ...HOST_FIELDS,
+        ...CLOUD_FIELDS,
+    ],
+    GuardExternalIdentity: ['provider', 'partition', 'account_id', 'region', 'arn', ...HOST_FIELDS, ...CLOUD_FIELDS],
+    GuardMcpConnection: [
+        'connection_id',
+        'capture_status',
+        'unavailable_reason',
+        'capture_observed_at',
+        'server_id',
+        'transport_ref',
+        'state',
+        'metadata_state',
+        'observed_at',
+        'evidence_kind',
+        'assessment',
+    ],
+    GuardOwner: ['owner_id', 'name', 'kind', ...HOST_FIELDS],
+    GuardCredentialReference: [
+        'credential_id',
+        'name',
+        'issuer_ref',
+        'audience_refs',
+        'recipient_refs',
+        'lifecycle_state',
+        'expires_at',
+        'rotation_status',
+        ...HOST_FIELDS,
+    ],
+    GuardDirectAccess: ['access_id', 'deployment_id', 'kind', 'target_ref', 'description', ...HOST_FIELDS],
+    GuardMcpOperation: ['connection_id', 'name', 'kind', 'fingerprint', 'evidence_kind', 'assessment'],
+});
+/** Defense in depth for summaries/diffs, including host-provided MapStore adapters. */
+export function safeProperties(node) {
+    return Object.fromEntries((MAP_PROPERTIES[node.label] ?? [])
+        .filter(key => Object.hasOwn(node.properties, key))
+        .map(key => [key, node.properties[key]]));
+}

package/dist/service/changes.d.ts

@@ -0,0 +1,5 @@
+import type { JsonObject, JsonValue, MapNode, MapProjection, MapSource, ReadScope } from '../types.js';
+import { QueryWork } from './work.js';
+export declare const IGNORE_DIFF: Set<string>;
+export declare function nodeState(node: MapNode, projection: MapProjection, work: QueryWork): string;
+export declare function retainedChanges(source: MapSource, args: Readonly<Record<string, JsonValue>>, scope: ReadScope, work: QueryWork): JsonObject;

package/dist/service/changes.js

@@ -0,0 +1,255 @@
+import { canonicalJson } from '@shieldaai/agent-guard/internal';
+import { fail } from '../common.js';
+import { safeProperties } from '../projection-fields.js';
+import { compare, ordered, page } from './ordering.js';
+import { targetVisibility } from './outside-guard.js';
+import { changeSummary, collection, focus, receipt, relationshipRows } from './summaries.js';
+import { connected, matching, nodeIds, QueryWork, string } from './work.js';
+export const IGNORE_DIFF = new Set([
+    'lastupdated',
+    'manifest_observed_at',
+    'manifest_revision',
+    'observed_at',
+    'capture_observed_at',
+    'cloud_observed_at',
+    // Recorded since 1.0.0; they cannot change for a task, so they are never a change.
+    'delegated',
+    'derived',
+]);
+export function nodeState(node, projection, work) {
+    const index = work.index(projection);
+    const properties = Object.fromEntries(Object.entries(safeProperties(node)).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) => compare(`${a.kind}:${a.target}`, `${b.kind}:${b.target}`));
+    return canonicalJson({ properties, edges });
+}
+export function retainedChanges(source, args, scope, work) {
+    const current = source.current, 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 projections = previous && previous !== current ? [current, previous] : [current];
+    const related = new Map();
+    for (const projection of projections) {
+        const impacted = new Map();
+        for (const agent of projection.nodes.filter(node => node.label === 'GuardAgent')) {
+            const brief = {
+                id: agent.entityId,
+                agentId: string(agent, 'agent_id'),
+                name: string(agent, 'name'),
+                sourceId: source.id,
+            };
+            for (const node of focus(projection, agent, work).nodes) {
+                const owners = impacted.get(node.entityId) ?? [];
+                owners.push(brief);
+                impacted.set(node.entityId, owners);
+            }
+        }
+        related.set(projection, impacted);
+    }
+    const selectedAgents = new Set(), selectedResources = new Set();
+    for (const projection of projections) {
+        for (const node of projection.nodes) {
+            work.step();
+            if (args.agentId && node.label === 'GuardAgent' && matching(node, args.agentId, 'agent_id'))
+                selectedAgents.add(node.entityId);
+            if (args.resourceId &&
+                node.label === 'GuardResourceBinding' &&
+                matching(node, args.resourceId, 'binding_id')) {
+                const selectors = connected(projection, new Set([node.id]), 'G_BINDS_SELECTOR', work);
+                const grants = connected(projection, nodeIds(selectors), 'G_TARGETS', work, true);
+                const tasks = connected(projection, nodeIds(grants), 'G_HAS_GRANT', work, true);
+                const deployment = connected(projection, nodeIds(tasks), 'G_ASSIGNED_TO', work);
+                const tools = connected(projection, nodeIds(grants), 'G_FOR_TOOL', work);
+                const toolIds = nodeIds(tools);
+                const executions = connected(projection, nodeIds(deployment), 'G_EXECUTES_FOR', work, true).filter(execution => connected(projection, new Set([execution.id]), 'G_EXECUTES_TOOL', work).some(tool => toolIds.has(tool.id)));
+                for (const item of [
+                    node,
+                    ...selectors,
+                    ...grants,
+                    ...tasks,
+                    ...deployment,
+                    ...tools,
+                    ...executions,
+                    ...connected(projection, new Set([node.id]), 'G_MAPS_TO', work),
+                    ...connected(projection, new Set([node.id]), 'G_RESOURCE_OWNED_BY', work),
+                    ...connected(projection, nodeIds(executions), 'G_USES_IDENTITY', work),
+                ])
+                    selectedResources.add(item.entityId);
+            }
+        }
+    }
+    if ((args.agentId && !selectedAgents.size) || (args.resourceId && !selectedResources.size))
+        fail('MAP_NOT_FOUND');
+    // Callers list the current snapshot's entries first, and the first entry for an id wins, so
+    // a renamed agent appears under its current name.
+    const uniqueAgents = (items) => {
+        const first = new Map();
+        for (const item of items)
+            if (!first.has(item.id))
+                first.set(item.id, item);
+        return ordered([...first.values()]);
+    };
+    const before = new Map(previous?.nodes.map(node => [node.entityId, node]) ?? []), after = new Map(current.nodes.map(node => [node.entityId, node]));
+    const beforeEdges = previous ? relationshipRows(previous, work) : [], afterEdges = relationshipRows(current, work);
+    const edgeKey = (edge) => JSON.stringify([edge.source, edge.target, edge.kind]);
+    const oldEdges = new Set(beforeEdges.map(edgeKey)), newEdges = new Set(afterEdges.map(edgeKey));
+    const relationships = {
+        added: previous ? afterEdges.filter(edge => !oldEdges.has(edgeKey(edge))) : [],
+        removed: previous ? beforeEdges.filter(edge => !newEdges.has(edgeKey(edge))) : [],
+    };
+    const outgoing = (edges) => {
+        const result = new Map();
+        for (const edge of edges) {
+            const list = result.get(edge.source) ?? [];
+            list.push(edge);
+            result.set(edge.source, list);
+        }
+        return result;
+    };
+    const oldOutgoing = outgoing(beforeEdges), newOutgoing = outgoing(afterEdges), changedOutgoing = outgoing([...relationships.added, ...relationships.removed]);
+    // A declared path's target is shown only when that resource is in the reader's scope.
+    const visibleNow = targetVisibility(current, scope, work), visibleBefore = previous ? targetVisibility(previous, scope, work) : visibleNow;
+    const state = (node, edges, visible) => node
+        ? {
+            properties: Object.fromEntries(Object.entries(safeProperties(node)).filter(([key, value]) => !IGNORE_DIFF.has(key) &&
+                !(node.label === 'GuardDirectAccess' &&
+                    key === 'target_ref' &&
+                    typeof value === 'string' &&
+                    !visible(value)))),
+            relationships: edges.get(node.entityId) ?? [],
+        }
+        : null;
+    const details = [];
+    if (previous)
+        for (const id of new Set([...after.keys(), ...before.keys()])) {
+            work.step();
+            const old = before.get(id), node = after.get(id), display = node ?? old;
+            if (node && old && nodeState(node, current, work) === nodeState(old, previous, work))
+                continue;
+            const oldState = state(old, oldOutgoing, visibleBefore), newState = state(node, newOutgoing, visibleNow);
+            const oldProps = oldState?.properties, newProps = newState?.properties;
+            const fields = [...new Set([...Object.keys(oldProps ?? {}), ...Object.keys(newProps ?? {})])]
+                .filter(key => canonicalJson((oldProps?.[key] ?? null)) !== canonicalJson((newProps?.[key] ?? null)))
+                .sort();
+            const edgeChanges = changedOutgoing.get(id) ?? [];
+            const categories = [];
+            if (display.label === 'GuardOwner' ||
+                fields.some(field => ['owner_id', 'team_id', 'ownership_status', 'ownership_source'].includes(field)) ||
+                edgeChanges.some(edge => ['G_OWNED_BY', 'G_RESOURCE_OWNED_BY'].includes(edge.kind)))
+                categories.push('ownership');
+            if (['GuardGrant', 'GuardTool', 'GuardTask'].includes(display.label) ||
+                edgeChanges.some(edge => ['G_HAS_GRANT', 'G_FOR_TOOL', 'G_TARGETS'].includes(edge.kind)))
+                categories.push('permissions');
+            if ([
+                'GuardDeployment',
+                'GuardResourceBinding',
+                'GuardExecutionBinding',
+                'GuardExternalResource',
+                'GuardExternalIdentity',
+                'GuardCredentialReference',
+                'GuardMcpConnection',
+                'GuardMcpOperation',
+            ].includes(display.label) ||
+                edgeChanges.some(edge => ![
+                    'G_OWNED_BY',
+                    'G_RESOURCE_OWNED_BY',
+                    'G_HAS_GRANT',
+                    'G_FOR_TOOL',
+                    'G_TARGETS',
+                    'G_DIRECT_ACCESS_FOR',
+                ].includes(edge.kind)))
+                categories.push('bindings');
+            // Host-declared paths around the guard, and a deployment's declaration status.
+            const outsideGuard = display.label === 'GuardDirectAccess' ||
+                fields.includes('direct_access_status') ||
+                edgeChanges.some(edge => edge.kind === 'G_DIRECT_ACCESS_FOR');
+            if (outsideGuard)
+                categories.push('outside_guard');
+            if (!categories.length)
+                categories.push('inventory');
+            const affected = uniqueAgents([
+                ...(related.get(current)?.get(id) ?? []),
+                ...(related.get(previous)?.get(id) ?? []),
+            ]);
+            if (args.agentId && !affected.some(agent => selectedAgents.has(agent.id)))
+                continue;
+            if (args.resourceId && !selectedResources.has(id))
+                continue;
+            if (args.changeKind && args.changeKind !== 'all' && !categories.includes(args.changeKind))
+                continue;
+            const navigation = display.label === 'GuardOwner' && string(display, 'owner_id')
+                ? {
+                    operation: 'list_agents',
+                    args: { sourceId: source.id, ownerId: string(display, 'owner_id') },
+                    scope: 'direct_current_ownership',
+                    limitation: 'Lists agents directly owned now; excludes indirect impact through resource ownership.',
+                }
+                : display.label === 'GuardResourceBinding' && node
+                    ? {
+                        operation: 'get_resource_access',
+                        args: { sourceId: source.id, resourceId: node.entityId },
+                        scope: 'current_observations',
+                    }
+                    : null;
+            details.push({
+                ...changeSummary(display),
+                kind: !old ? 'added' : !node ? 'removed' : 'changed',
+                categories,
+                ...(outsideGuard ? { evidenceKind: 'declared' } : {}),
+                changedFields: fields,
+                before: oldState,
+                after: newState,
+                affectedAgents: affected.slice(0, 100),
+                affectedAgentsTotal: affected.length,
+                affectedAgentsTruncated: affected.length > 100,
+                affectedAgentNavigation: navigation,
+            });
+        }
+    ordered(details);
+    const { items, ...pagination } = page(details, args);
+    const explicitlyPaged = args.offset !== undefined || args.limit !== undefined;
+    const companion = explicitlyPaged ? items : details;
+    const changedIds = new Set(companion.map(item => item.entityId));
+    const relevantEdge = (edge) => changedIds.has(edge.source);
+    const affected = uniqueAgents(companion.flatMap(item => [
+        ...(related.get(current)?.get(item.entityId) ?? []),
+        ...(previous ? (related.get(previous)?.get(item.entityId) ?? []) : []),
+    ]));
+    return {
+        sourceId: source.id,
+        from: previous ? receipt(source, previous) : null,
+        to: receipt(source),
+        changes: Object.fromEntries(['added', 'removed', 'changed'].map(kind => [
+            kind,
+            companion
+                .filter(item => item.kind === kind)
+                .map(item => ({ entityId: item.entityId, label: item.label, name: item.name })),
+        ])),
+        details: items,
+        ...pagination,
+        relationships: {
+            added: relationships.added.filter(relevantEdge),
+            removed: relationships.removed.filter(relevantEdge),
+        },
+        changeSummaryScope: explicitlyPaged ? 'page' : 'retained',
+        affectedAgents: affected.slice(0, 100),
+        affectedAgentsTotal: affected.length,
+        affectedAgentsTruncated: affected.length > 100,
+        coverageGap: previous === null,
+        policyHistory: 'not_collected',
+        collection,
+        limitations: [
+            'Net changes in authorized retained snapshots only; not an invocation or intermediate-event log.',
+            'Declared permission and binding changes do not establish effective access gain or loss.',
+            'Current IAM policy observations are separate from retained Guard snapshots; policy history is not collected.',
+        ],
+    };
+}

package/dist/service/context.d.ts

@@ -0,0 +1,33 @@
+import type { JsonObject, MapReadRequest, MapView, ReadScope } from '../types.js';
+import type { QueryArguments } from './schemas.js';
+import type { FocusedGraph } from './summaries.js';
+import { QueryWork } from './work.js';
+/** What every operation handler is given: the validated request, the clock and the bounded reads. */
+export interface OperationContext {
+    readonly scope: ReadScope;
+    readonly args: QueryArguments;
+    /** The service clock at the start of the query, in milliseconds. */
+    readonly now: number;
+    readonly work: QueryWork;
+    /** The response byte limit; separate work budgets are sized from it. */
+    readonly maxBytes: number;
+    readonly staleSeconds: number;
+    /** One store read under this query's scope, with the query timeout unless a shorter one is given. */
+    read(request: MapReadRequest, timeout?: number): Promise<MapView>;
+}
+export interface OperationResult {
+    data: JsonObject;
+    /** Only get_agent_access returns a graph; the service drops it when it is too large. */
+    graph?: FocusedGraph;
+}
+export interface Operation {
+    /**
+     * The read the service runs before the handler, or null when the handler plans its own
+     * reads. It also refuses argument combinations that no read could answer.
+     */
+    request(args: QueryArguments): MapReadRequest | null;
+    run(context: OperationContext, view: MapView): OperationResult | Promise<OperationResult>;
+}
+export declare const sourceSelection: (args: QueryArguments) => {
+    sourceId?: string;
+};

package/dist/service/context.js

@@ -0,0 +1,2 @@
+import { number, QueryWork, string } from './work.js';
+export const sourceSelection = (args) => args.sourceId ? { sourceId: args.sourceId } : {};

package/dist/service/discovery.d.ts

@@ -0,0 +1,6 @@
+import type { JsonObject, MapSource, MapUndeclaredActivity } from '../types.js';
+export declare const ALL_TEAMS_NOTE = "Shown only to readers with all-teams visibility, because what it lists belongs to no team. This note is the same whether or not anything would be listed.";
+export declare const notVisible: () => JsonObject;
+export declare function undeclaredCounts(source: MapSource, activity: MapUndeclaredActivity): JsonObject;
+export declare const UNDECLARED_LIMITATIONS: string[];
+export declare const UNCLAIMED_LIMITATIONS: string[];

package/dist/service/discovery.js

@@ -0,0 +1,31 @@
+// Discovery views list what belongs to no team, so only an all-teams reader sees them. A
+// team-scoped reader gets this fixed answer without any read: no names, no counts, and the
+// same words whether or not anything would be listed.
+export const ALL_TEAMS_NOTE = 'Shown only to readers with all-teams visibility, because what it lists belongs to no team. This note is the same whether or not anything would be listed.';
+export const notVisible = () => ({
+    visibility: 'all_teams_required',
+    status: 'not_visible',
+    note: ALL_TEAMS_NOTE,
+});
+export function undeclaredCounts(source, activity) {
+    return {
+        // Counting stops at 10,000: a minimum is partial, not complete.
+        status: activity.tasksCapped || activity.principalsCapped ? 'partial' : 'complete',
+        tasks: activity.tasks,
+        tasksIsMinimum: activity.tasksCapped,
+        principals: activity.principals,
+        principalsIsMinimum: activity.principalsCapped,
+        // Without a manifest no agent can be declared, so everything the executor saw counts.
+        manifest: source.profile === 'core' ? 'not_collected' : 'collected',
+    };
+}
+export const UNDECLARED_LIMITATIONS = [
+    'Only activity that ran through an enrolled executor is seen. An agent that does not use the guard leaves nothing here.',
+    'A task is undeclared when no manifest task binding assigns it to a deployment of a declared agent. parentDeclared marks a task whose direct parent is assigned: usually a sub-task that only lacks its own binding.',
+    'A lead to follow up, not a finding. Listing grants or blocks nothing.',
+];
+export const UNCLAIMED_LIMITATIONS = [
+    'Candidates to review, not findings: most IAM roles and users are not agents, and the map cannot tell which are.',
+    'An identity is claimed when a declared execution binding names its exact ARN in a current snapshot you can read. Role assumption, instance profiles and federation are not followed.',
+    'Only IAM roles and users of an enrolled AWS account are collected. An account that is missing, stale or inconsistent reads unknown, and its identities are not listed. Listing grants or blocks nothing.',
+];

package/dist/service/explain.d.ts

@@ -0,0 +1,12 @@
+import type { JsonObject, MapNode, MapProjection, ReadScope } from '../types.js';
+import { QueryWork } from './work.js';
+export declare function knownBlockers(task: MapNode, tool: MapNode | undefined, now: number): string[];
+export declare function externalEvidence(projection: MapProjection, task: MapNode, toolName: string, resourceId: string, work: QueryWork, policySelection?: {
+    action?: string;
+    resourceBindingId?: string;
+}): JsonObject;
+export declare const COMMON_UNKNOWN: string[];
+export declare function explain(projection: MapProjection, scope: ReadScope, task: MapNode, toolName: string, resourceId: string, now: number, work: QueryWork, policySelection?: {
+    action?: string;
+    resourceBindingId?: string;
+}): JsonObject;

package/dist/service/explain.js

@@ -0,0 +1,126 @@
+import { safeProperties } from '../projection-fields.js';
+import { jsonList } from './json.js';
+import { policyCoverage, policyCoverageOf, selectedPolicy } from './policy.js';
+import { grantSummary } from './summaries.js';
+import { bindingKey, connected, nodeIds, number, QueryWork, string, strings, unique } from './work.js';
+export 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;
+}
+export 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);
+    const bound = work.lookup(projection).bindings.get(bindingKey(toolName, resourceId)) ?? [];
+    work.step(bound.length);
+    const resources = bound.filter(node => !policySelection.resourceBindingId || node.entityId === policySelection.resourceBindingId);
+    const policy = selectedPolicy(projection, work, {
+        task,
+        executions,
+        resources,
+        ...(policySelection.action ? { action: policySelection.action } : {}),
+    });
+    return {
+        // Allowlisted properties only, also for a host-provided store.
+        executionBindings: executions.map(node => ({
+            id: node.entityId,
+            ...safeProperties(node),
+            identities: connected(projection, new Set([node.id]), 'G_USES_IDENTITY', work).map(safeProperties),
+            connections: connected(projection, new Set([node.id]), 'G_VIA_CONNECTION', work).map(safeProperties),
+        })),
+        resourceBindings: resources.map(node => ({
+            id: node.entityId,
+            ...safeProperties(node),
+            targets: connected(projection, new Set([node.id]), 'G_MAPS_TO', work).map(safeProperties),
+        })),
+        policyEvidence: jsonList(policy),
+        policyCoverage: policyCoverageOf(projection, 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.',
+        ],
+    };
+}
+export const COMMON_UNKNOWN = [
+    'live_authorization',
+    'request_arguments_and_resolution',
+    'custom_policy',
+    'backend_authorization',
+    'action_approval',
+];
+export function explain(projection, scope, task, toolName, resourceId, now, work, policySelection = {}) {
+    const index = work.index(projection), nodes = index.nodes;
+    const tool = work.lookup(projection).tools.get(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.',
+        ],
+    };
+}

package/dist/service/flags.d.ts

@@ -0,0 +1,20 @@
+import { type FlagGraph } from '../boundary-flags.js';
+import { type JsonObject, type MapNode, type MapProjection, type ReadScope } from '../types.js';
+import { QueryWork } from './work.js';
+/**
+ * The bounded, read-only graph view the boundary flags use. Sensitive bindings for `*` grants
+ * come from the store's wildcard read when it ran (one-agent boundary reads); a team-wide read
+ * already holds every in-scope binding, indexed once per projection.
+ */
+export declare const sensitiveIndex: WeakMap<MapProjection, Map<string, {
+    id: string;
+    sensitivity: string;
+}[]>>;
+export declare function flagGraph(projection: MapProjection, work: QueryWork): FlagGraph;
+/** Task expiry is judged at the snapshot's own capture time, so list and detail agree. */
+export declare function agentFlags(projection: MapProjection, agent: MapNode, scope: ReadScope, work: QueryWork): import("../boundary-flags.js").DangerousThree;
+/**
+ * The detail flag with its own work budget: a very large lineage degrades the flag to
+ * `unknown`, it never fails the rest of get_agent_access.
+ */
+export declare function detailFlags(projection: MapProjection, agent: MapNode, scope: ReadScope, remaining: number, maxBytes: number): JsonObject;