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

package/dist/service/flags.js

@@ -0,0 +1,70 @@
+import { DANGEROUS_THREE_LIMITATIONS, dangerousThree } from '../boundary-flags.js';
+import { MapQueryError } from '../types.js';
+import { jsonObject } from './json.js';
+import { connected, number, QueryWork, string } 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 const sensitiveIndex = new WeakMap();
+export function flagGraph(projection, work) {
+    return {
+        linked: (node, kind, reverse = false) => connected(projection, new Set([node.id]), kind, work, reverse),
+        sensitiveBindings: tool => {
+            if (projection.wildcardSensitivity)
+                return Object.hasOwn(projection.wildcardSensitivity, tool) ? projection.wildcardSensitivity[tool] : [];
+            let index = sensitiveIndex.get(projection);
+            if (!index) {
+                work.step(projection.nodes.length);
+                index = new Map();
+                for (const node of projection.nodes) {
+                    const name = string(node, 'tool'), sensitivity = string(node, 'sensitivity');
+                    if (node.label !== 'GuardResourceBinding' || name === null)
+                        continue;
+                    if (sensitivity !== 'confidential' && sensitivity !== 'restricted')
+                        continue;
+                    const items = index.get(name) ?? [];
+                    items.push({ id: node.entityId, sensitivity });
+                    index.set(name, items);
+                }
+                for (const [name, items] of index)
+                    index.set(name, items.sort((a, b) => (a.id < b.id ? -1 : a.id > b.id ? 1 : 0)).slice(0, 5));
+                sensitiveIndex.set(projection, index);
+            }
+            return index.get(tool) ?? [];
+        },
+        step: amount => work.step(amount),
+    };
+}
+/** Task expiry is judged at the snapshot's own capture time, so list and detail agree. */
+export function agentFlags(projection, agent, scope, work) {
+    return dangerousThree(flagGraph(projection, work), agent, Date.parse(projection.generatedAt), scope.allTeams, projection.ancestorsNotLoaded === true);
+}
+/**
+ * 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 function detailFlags(projection, agent, scope, remaining, maxBytes) {
+    try {
+        return jsonObject(agentFlags(projection, agent, scope, new QueryWork(Math.max(1, remaining - 25), maxBytes)));
+    }
+    catch (error) {
+        const code = error instanceof MapQueryError ? error.code : '';
+        if (code !== 'MAP_LIMIT_EXCEEDED' && code !== 'MAP_TIMEOUT')
+            throw error;
+        return jsonObject({
+            kind: 'dangerous_three',
+            status: 'unknown',
+            taskId: null,
+            legs: { privateData: 'unknown', outsideContent: 'unknown', externalSend: 'unknown' },
+            evidence: [],
+            evidenceTruncated: false,
+            notes: [code === 'MAP_TIMEOUT' ? 'flags_timeout' : 'flags_limit_exceeded'],
+            liveTasks: 0,
+            evidenceKind: 'declared',
+            assessment: 'unknown',
+            limitations: DANGEROUS_THREE_LIMITATIONS,
+        });
+    }
+}

package/dist/service/inventory.d.ts

@@ -0,0 +1,4 @@
+import type { JsonObject, MapNode, MapProjection, MapSource } from '../types.js';
+import { sections } from './schemas.js';
+import { QueryWork } from './work.js';
+export declare function inventorySections(source: MapSource, projection: MapProjection, agent: MapNode, work: QueryWork): Record<(typeof sections)[number], JsonObject[]>;

package/dist/service/inventory.js

@@ -0,0 +1,62 @@
+import { safeProperties } from '../projection-fields.js';
+import { ordered } from './ordering.js';
+import { sections } from './schemas.js';
+import { agentSummary, deployments, grantSummary, hostObservation, ownerSummary, relationshipRows, resourceSummary, taskSummary, } from './summaries.js';
+import { connected, number, QueryWork, string, strings } from './work.js';
+export function inventorySections(source, projection, agent, work) {
+    const byLabel = (label) => projection.nodes.filter(node => node.label === label);
+    const described = (label) => byLabel(label).map(node => ({ id: node.entityId, ...safeProperties(node) }));
+    const summary = agentSummary(source, projection, agent, work);
+    return {
+        overview: [
+            {
+                purpose: summary.purpose,
+                lifecycleState: summary.lifecycleState,
+                ownershipStatus: summary.ownershipStatus,
+                ownershipSource: summary.ownershipSource,
+                ownerName: summary.ownerName,
+                ...hostObservation(agent),
+            },
+        ],
+        owners: ordered(byLabel('GuardOwner').map(node => ownerSummary(source, projection, node, work, false))),
+        deployments: ordered(byLabel('GuardDeployment').map(node => ({
+            id: node.entityId,
+            deploymentId: string(node, 'deployment_id'),
+            environment: string(node, 'environment'),
+            runtimeRef: string(node, 'runtime_ref'),
+            workloadGeneration: string(node, 'workload_generation'),
+            buildRef: string(node, 'build_ref'),
+            bindingAuthority: string(node, 'binding_authority'),
+            // The same rule as get_agent_access: `found` needs an entry in the read.
+            directAccessStatus: connected(projection, new Set([node.id]), 'G_DIRECT_ACCESS_FOR', work, true).length
+                ? 'found'
+                : string(node, 'direct_access_status') === 'none_declared'
+                    ? 'none_declared'
+                    : 'unknown',
+            ...hostObservation(node),
+        }))),
+        tasks: ordered(byLabel('GuardTask').map(taskSummary)),
+        permissions: ordered(byLabel('GuardGrant').map(grantSummary)),
+        resources: ordered(byLabel('GuardResourceBinding').map(node => resourceSummary(source, projection, node, work))),
+        connections: ordered(described('GuardMcpConnection')),
+        credentials: ordered(byLabel('GuardCredentialReference').map(node => ({
+            id: node.entityId,
+            credentialId: string(node, 'credential_id'),
+            name: string(node, 'name'),
+            issuerRef: string(node, 'issuer_ref'),
+            audienceRefs: strings(node, 'audience_refs'),
+            recipientRefs: strings(node, 'recipient_refs'),
+            lifecycleState: string(node, 'lifecycle_state') ?? 'unknown',
+            expiresAt: string(node, 'expires_at'),
+            rotationStatus: string(node, 'rotation_status') ?? 'unknown',
+            ...hostObservation(node),
+        }))),
+        relationships: relationshipRows(projection, work),
+        tools: ordered(described('GuardTool')),
+        bindings: ordered(projection.nodes
+            .filter(node => ['GuardExecutionBinding', 'GuardResourceBinding'].includes(node.label))
+            .map(node => ({ id: node.entityId, kind: node.label, ...safeProperties(node) }))),
+        identities: ordered(described('GuardExternalIdentity')),
+        policies: [],
+    };
+}

package/dist/service/json.d.ts

@@ -0,0 +1,8 @@
+import type { JsonObject } from '../types.js';
+/**
+ * The map's record interfaces (`MapCoverage`, `MapPolicyEvidence`, flag results and so on) hold
+ * only JSON values, but an interface has no index signature, so TypeScript will not treat one as
+ * a `JsonObject`. These two helpers are the only place that says so.
+ */
+export declare const jsonObject: (value: object) => JsonObject;
+export declare const jsonList: (values: readonly object[]) => readonly JsonObject[];

package/dist/service/json.js

@@ -0,0 +1,7 @@
+/**
+ * The map's record interfaces (`MapCoverage`, `MapPolicyEvidence`, flag results and so on) hold
+ * only JSON values, but an interface has no index signature, so TypeScript will not treat one as
+ * a `JsonObject`. These two helpers are the only place that says so.
+ */
+export const jsonObject = (value) => value;
+export const jsonList = (values) => values;

package/dist/service/operations/discovery.d.ts

@@ -0,0 +1,5 @@
+import type { Operation } from '../context.js';
+/** Tasks or caller principals of one source that no declared agent accounts for. */
+export declare const listUndeclaredActivity: Operation;
+/** IAM roles and users of the enrolled AWS accounts that no declared agent names. */
+export declare const listUnclaimedIdentities: Operation;

package/dist/service/operations/discovery.js

@@ -0,0 +1,90 @@
+import { fail } from '../../common.js';
+import { notVisible, UNCLAIMED_LIMITATIONS, UNDECLARED_LIMITATIONS, undeclaredCounts } from '../discovery.js';
+import { page } from '../ordering.js';
+import { pageArguments } from '../schemas.js';
+import { findSource, freshness, receipt } from '../summaries.js';
+import { string } from '../work.js';
+// Discovery operations use their own bounded reads, and none at all for a team-scoped reader.
+/** Tasks or caller principals of one source that no declared agent accounts for. */
+export const listUndeclaredActivity = {
+    request: () => null,
+    async run({ scope, args, work, read }) {
+        if (!scope.allTeams)
+            return { data: notVisible() };
+        const kind = (args.kind ?? 'tasks');
+        const { offset, limit } = pageArguments(args);
+        const found = await read({ sourceId: args.sourceId, undeclared: true, page: { kind, offset, limit } });
+        const source = findSource(found, args.sourceId);
+        const activity = source.current.undeclared;
+        if (!activity || activity.page?.kind !== kind)
+            fail('MAP_UNAVAILABLE');
+        work.step(activity.page.items.length);
+        const total = kind === 'tasks' ? activity.tasks : activity.principals;
+        const minimum = kind === 'tasks' ? activity.tasksCapped : activity.principalsCapped;
+        return {
+            data: {
+                visibility: 'all_teams',
+                kind,
+                items: activity.page.items.map(item => ({ ...item, evidenceKind: 'observed', assessment: 'unknown' })),
+                total,
+                totalIsMinimum: minimum,
+                offset,
+                limit,
+                truncated: minimum || offset + limit < total,
+                counts: undeclaredCounts(source, activity),
+                receipt: receipt(source),
+                assessment: 'unknown',
+                limitations: UNDECLARED_LIMITATIONS,
+            },
+        };
+    },
+};
+/** IAM roles and users of the enrolled AWS accounts that no declared agent names. */
+export const listUnclaimedIdentities = {
+    request: () => null,
+    async run({ scope, args, now, work, staleSeconds, read }) {
+        if (!scope.allTeams)
+            return { data: notVisible() };
+        const { offset, limit } = pageArguments(args);
+        const found = await read({ unclaimedIdentities: true, page: { offset, limit } });
+        const result = found.unclaimedIdentities;
+        if (!result)
+            fail('MAP_UNAVAILABLE');
+        work.step(result.accounts.length + result.identities.length + found.sources.length);
+        const complete = result.accounts.filter(account => account.status === 'complete').length;
+        // No usable collection: nothing is known, so no total and no list. Some unusable: the
+        // total and the list cover the complete accounts only.
+        const status = !complete ? 'unknown' : complete === result.accounts.length ? 'complete' : 'partial';
+        return {
+            data: {
+                visibility: 'all_teams',
+                status,
+                reason: result.accounts.length ? null : 'cloud_not_collected',
+                identities: result.identities.map(identity => ({
+                    ...identity,
+                    candidate: true,
+                    evidenceKind: 'provider_inventory',
+                    assessment: 'unknown',
+                })),
+                total: status === 'unknown' ? null : result.total,
+                offset,
+                limit,
+                truncated: status !== 'unknown' && offset + limit < result.total,
+                accounts: result.accounts.map(account => ({
+                    ...account,
+                    ...(account.observedAt ? freshness(account.observedAt, now, staleSeconds) : {}),
+                })),
+                bindingsWithoutIdentity: result.bindingsWithoutIdentity,
+                // The snapshots whose declared bindings decided what counts as claimed.
+                declaredFrom: found.sources.map(source => ({
+                    sourceId: source.id,
+                    tenantId: source.tenantId,
+                    snapshotId: source.current.snapshotId,
+                    generatedAt: source.current.generatedAt,
+                })),
+                assessment: 'unknown',
+                limitations: UNCLAIMED_LIMITATIONS,
+            },
+        };
+    },
+};

package/dist/service/operations/explain-access.d.ts

@@ -0,0 +1,3 @@
+import { type Operation } from '../context.js';
+/** Why one task may or may not use one tool on one resource selector, as far as the snapshot says. */
+export declare const explainAccess: Operation;

package/dist/service/operations/explain-access.js

@@ -0,0 +1,25 @@
+import { fail } from '../../common.js';
+import { sourceSelection } from '../context.js';
+import { explain } from '../explain.js';
+import { findSource, receipt } from '../summaries.js';
+import { matching, string } from '../work.js';
+/** Why one task may or may not use one tool on one resource selector, as far as the snapshot says. */
+export const explainAccess = {
+    // The policy evidence is narrowed to this task, tool and selector.
+    request: args => ({
+        ...sourceSelection(args),
+        policy: { taskId: args.taskId, tool: args.tool, resourceRef: args.resourceId },
+    }),
+    run({ scope, args, now, work }, view) {
+        const source = findSource(view, args.sourceId);
+        const task = source.current.nodes.find(node => node.label === 'GuardTask' && matching(node, args.taskId, 'task_id'));
+        if (!task)
+            fail('MAP_NOT_FOUND');
+        return {
+            data: {
+                ...explain(source.current, scope, task, args.tool, args.resourceId, now, work),
+                receipt: receipt(source),
+            },
+        };
+    },
+};

package/dist/service/operations/find-agents-with-access.d.ts

@@ -0,0 +1,3 @@
+import { type Operation } from '../context.js';
+/** Agents whose declared grants and host bindings map to one resource reference and cloud action. */
+export declare const findAgentsWithAccess: Operation;

package/dist/service/operations/find-agents-with-access.js

@@ -0,0 +1,120 @@
+import { safeProperties } from '../../projection-fields.js';
+import { MapQueryError } from '../../types.js';
+import { sourceSelection } from '../context.js';
+import { explain } from '../explain.js';
+import { jsonList } from '../json.js';
+import { policyCoverage, policyCoverageOf, selectedPolicy } from '../policy.js';
+import { agentSummary, focus } from '../summaries.js';
+import { connected, nodeIds, number, QueryWork, string, strings } from '../work.js';
+/** Agents whose declared grants and host bindings map to one resource reference and cloud action. */
+export const findAgentsWithAccess = {
+    // A resource most of the fleet uses can match more pairs than one read evaluates: the
+    // candidates are then listed with policy coverage unknown instead of failing.
+    request: args => ({
+        ...sourceSelection(args),
+        policy: { resourceRef: args.resourceRef, action: args.action, optional: true },
+    }),
+    run({ scope, args, now, work, maxBytes }, view) {
+        const candidates = [];
+        const limit = args.limit ?? 50;
+        let truncated = false;
+        let truncatedReason = null;
+        // The search counts its own work and evidence bytes (leaving room for the envelope), so
+        // running out ends the list early instead of failing the answer.
+        const search = new QueryWork(Math.max(1, work.remaining() - 25), Math.floor(maxBytes * 0.8));
+        try {
+            candidateSearch: for (const source of view.sources) {
+                // A binding enters an agent's focus only via deployment -> agent <- task -> grant -> resource
+                // <- binding. Walking that chain backwards from the matching bindings yields exactly the
+                // agents that can have evidence; the full per-agent check below still runs unchanged.
+                const projection = source.current;
+                const matches = projection.nodes.filter(node => {
+                    search.step();
+                    return (node.label === 'GuardResourceBinding' &&
+                        strings(node, 'actions').includes(args.action) &&
+                        (string(node, 'resource_ref') === args.resourceRef ||
+                            connected(projection, new Set([node.id]), 'G_MAPS_TO', search).some(external => string(external, 'arn') === args.resourceRef)));
+                });
+                if (!matches.length)
+                    continue;
+                const resources = nodeIds(connected(projection, nodeIds(matches), 'G_BINDS_SELECTOR', search));
+                const grants = nodeIds(connected(projection, resources, 'G_TARGETS', search, true));
+                const tasks = nodeIds(connected(projection, grants, 'G_HAS_GRANT', search, true));
+                const deploymentIds = nodeIds(connected(projection, tasks, 'G_ASSIGNED_TO', search).filter(node => node.label === 'GuardDeployment'));
+                const reachable = nodeIds(connected(projection, deploymentIds, 'G_INSTANCE_OF', search));
+                for (const agent of projection.nodes.filter(node => node.label === 'GuardAgent' && reachable.has(node.id))) {
+                    search.step();
+                    const selected = focus(source.current, agent, search), selectedProjection = { ...source.current, ...selected };
+                    const bindings = selected.nodes.filter(node => node.label === 'GuardResourceBinding' && strings(node, 'actions').includes(args.action));
+                    const evidence = [];
+                    for (const binding of bindings) {
+                        search.step();
+                        const external = connected(selectedProjection, new Set([binding.id]), 'G_MAPS_TO', search)[0];
+                        if (string(binding, 'resource_ref') !== args.resourceRef &&
+                            (!external || string(external, 'arn') !== args.resourceRef))
+                            continue;
+                        const toolName = string(binding, 'tool'), resource = string(binding, 'resource_ref');
+                        if (!toolName || !resource)
+                            continue;
+                        for (const task of selected.nodes.filter(node => node.label === 'GuardTask')) {
+                            search.step();
+                            if (!connected(selectedProjection, new Set([task.id]), 'G_HAS_GRANT', search).some(grant => string(grant, 'tool') === toolName &&
+                                strings(grant, 'resources').some(item => item === '*' || item === resource)))
+                                continue;
+                            if (candidates.length >= limit) {
+                                truncated = true;
+                                break candidateSearch;
+                            }
+                            const deployment = connected(selectedProjection, new Set([task.id]), 'G_ASSIGNED_TO', search);
+                            const executions = connected(selectedProjection, nodeIds(deployment), 'G_EXECUTES_FOR', search, true).filter(node => string(node, 'tool') === toolName);
+                            const policy = selectedPolicy(source.current, search, {
+                                task,
+                                executions,
+                                resources: [binding],
+                                action: args.action,
+                            });
+                            evidence.push(search.evidence({
+                                taskId: string(task, 'task_id'),
+                                tool: toolName,
+                                resourceRef: resource,
+                                action: args.action,
+                                scope: string(binding, 'scope'),
+                                externalResource: external ? safeProperties(external) : null,
+                                executionBindings: executions.map(node => ({
+                                    id: node.entityId,
+                                    ...safeProperties(node),
+                                    identities: connected(selectedProjection, new Set([node.id]), 'G_USES_IDENTITY', search).map(safeProperties),
+                                })),
+                                policyEvidence: jsonList(policy),
+                                policyCoverage: policyCoverageOf(source.current, policy),
+                                explanation: explain(source.current, scope, task, toolName, resource, now, search, {
+                                    action: args.action,
+                                    resourceBindingId: binding.entityId,
+                                }),
+                            }));
+                        }
+                    }
+                    if (evidence.length)
+                        candidates.push({
+                            agent: agentSummary(source, source.current, agent, search),
+                            evidence,
+                            assessment: 'unknown',
+                            limitations: [
+                                'Potential access candidates; no effective permission decision.',
+                                'Cloud containment is not exact object authorization.',
+                            ],
+                        });
+                }
+            }
+        }
+        catch (error) {
+            // Out of work or evidence room: the candidates completed so far stand and the result
+            // says it is incomplete. With none completed there is nothing honest to return.
+            if (!(error instanceof MapQueryError) || error.code !== 'MAP_LIMIT_EXCEEDED' || !candidates.length)
+                throw error;
+            truncated = true;
+            truncatedReason = 'work_limit';
+        }
+        return { data: { candidates, truncated, ...(truncatedReason ? { truncatedReason } : {}) } };
+    },
+};

package/dist/service/operations/get-agent-access.d.ts

@@ -0,0 +1,3 @@
+import { type Operation } from '../context.js';
+/** One agent's neighborhood: evidence lists, boundary flags, outside-guard access and a graph. */
+export declare const getAgentAccess: Operation;

package/dist/service/operations/get-agent-access.js

@@ -0,0 +1,75 @@
+import { safeProperties } from '../../projection-fields.js';
+import { sourceSelection } from '../context.js';
+import { detailFlags } from '../flags.js';
+import { jsonList } from '../json.js';
+import { directAccess, identityScope, targetVisibility } from '../outside-guard.js';
+import { policyCoverage, policyCoverageOf, selectedPolicy } from '../policy.js';
+import { agentSummary, deployments, findAgent, findSource, focus, grantSummary, receipt, taskSummary, } from '../summaries.js';
+import { string } from '../work.js';
+/** One agent's neighborhood: evidence lists, boundary flags, outside-guard access and a graph. */
+export const getAgentAccess = {
+    // Boundary evidence (ancestors, `*` bindings, identity scope) is read only here, where it is
+    // shown. Past the pair limit the policy evidence reads unknown instead of failing the answer.
+    request: args => ({
+        ...sourceSelection(args),
+        agentId: args.agentId,
+        policy: { optional: true },
+        boundary: true,
+    }),
+    run({ scope, args, work, maxBytes }, view) {
+        const source = findSource(view, args.sourceId), projection = source.current;
+        const agent = findAgent(projection, args.agentId);
+        const focused = focus(projection, agent, work);
+        // The response graph carries node properties too: withhold out-of-scope targets there.
+        const visibleTarget = targetVisibility(projection, scope, work);
+        // Allowlisted properties only, also for a host-provided store.
+        const graph = {
+            ...focused,
+            nodes: focused.nodes.map(node => {
+                const target = node.label === 'GuardDirectAccess' ? string(node, 'target_ref') : null;
+                const allowed = safeProperties(node);
+                if (target === null || visibleTarget(target))
+                    return { ...node, properties: allowed };
+                const { target_ref: _withheld, ...properties } = allowed;
+                return { ...node, properties };
+            }),
+        };
+        const policy = selectedPolicy(projection, work, { nodes: graph.nodes });
+        return {
+            graph,
+            data: {
+                agent: agentSummary(source, projection, agent, work),
+                deployments: graph.nodes
+                    .filter(node => node.label === 'GuardDeployment')
+                    .map(node => ({
+                    id: node.entityId,
+                    deploymentId: string(node, 'deployment_id'),
+                    environment: string(node, 'environment'),
+                })),
+                tasks: graph.nodes.filter(node => node.label === 'GuardTask').map(taskSummary),
+                grants: graph.nodes.filter(node => node.label === 'GuardGrant').map(grantSummary),
+                connections: graph.nodes
+                    .filter(node => node.label === 'GuardMcpConnection')
+                    .map(node => ({ id: node.entityId, ...safeProperties(node) })),
+                bindings: graph.nodes
+                    .filter(node => ['GuardExecutionBinding', 'GuardResourceBinding'].includes(node.label))
+                    .map(node => ({ id: node.entityId, kind: node.label, ...safeProperties(node) })),
+                policyEvidence: jsonList(policy),
+                policyCoverage: policyCoverageOf(projection, policy),
+                outsideGuard: {
+                    directAccess: directAccess(projection, graph, scope, work),
+                    identityScope: identityScope(projection, graph),
+                },
+                boundaryFlags: [detailFlags(projection, agent, scope, work.remaining(), maxBytes)],
+                receipt: receipt(source),
+                assessment: 'unknown',
+                graphStatus: 'included',
+                limitations: [
+                    'Declared and observed evidence only; current executor admission is required.',
+                    'External object and prefix bindings retain their original scope.',
+                    'Only S3 identity policies and host declarations are checked. Bucket policies, SCPs and permission boundaries are not, so identity-scope buckets are candidates and a deny elsewhere can remove the access. none_declared is the host claim, not a check, and no status means safe.',
+                ],
+            },
+        };
+    },
+};

package/dist/service/operations/get-agent-inventory.d.ts

@@ -0,0 +1,3 @@
+import { type Operation } from '../context.js';
+/** One paged section of one agent's inventory, with the size of every section. */
+export declare const getAgentInventory: Operation;

package/dist/service/operations/get-agent-inventory.js

@@ -0,0 +1,42 @@
+import { sourceSelection } from '../context.js';
+import { inventorySections } from '../inventory.js';
+import { jsonList } from '../json.js';
+import { page } from '../ordering.js';
+import { policyCoverage, policyCoverageOf, selectedPolicy } from '../policy.js';
+import { agentSummary, collection, findAgent, findSource, focus, receipt } from '../summaries.js';
+import { string } from '../work.js';
+/** One paged section of one agent's inventory, with the size of every section. */
+export const getAgentInventory = {
+    // One agent can hold more task/binding/action pairs than one read evaluates: its policy
+    // evidence then reads unknown (`limit_exceeded`) and the rest of the answer stands.
+    request: args => ({ ...sourceSelection(args), agentId: args.agentId, policy: { optional: true } }),
+    run({ args, work }, view) {
+        const source = findSource(view, args.sourceId), agent = findAgent(source.current, args.agentId);
+        const selected = { ...source.current, ...focus(source.current, agent, work) };
+        const groups = inventorySections(source, selected, agent, work), section = (args.section ?? 'overview');
+        const policy = selectedPolicy(source.current, work, { nodes: selected.nodes });
+        groups.policies = [...jsonList(policy)];
+        // Policy evidence the store did not load has no size. Its count and the total of its
+        // section are null (as for any total that is not known), never zero: an empty list here
+        // is "not evaluated", not "none".
+        const policyNotLoaded = source.current.policyEvidenceNotLoaded === true;
+        return {
+            data: {
+                agent: agentSummary(source, selected, agent, work),
+                section,
+                ...page(groups[section], args),
+                ...(policyNotLoaded && section === 'policies' ? { total: null } : {}),
+                counts: Object.fromEntries(Object.entries(groups)
+                    .filter(([key]) => key !== 'overview')
+                    .map(([key, value]) => [key, policyNotLoaded && key === 'policies' ? null : value.length])),
+                policyEvidence: section === 'policies' ? page(groups.policies, args).items : [],
+                policyCoverage: policyCoverageOf(source.current, policy),
+                receipt: receipt(source),
+                assessment: 'unknown',
+                graphStatus: 'not_requested',
+                collection,
+                limitations: ['Read-only host observations and declared grants; current execution still requires admission.'],
+            },
+        };
+    },
+};

package/dist/service/operations/get-changes.d.ts

@@ -0,0 +1,3 @@
+import { type Operation } from '../context.js';
+/** What changed between a source's current snapshot and its previous retained one. */
+export declare const getChanges: Operation;

package/dist/service/operations/get-changes.js

@@ -0,0 +1,11 @@
+import { retainedChanges } from '../changes.js';
+import { sourceSelection } from '../context.js';
+import { findSource } from '../summaries.js';
+import { string } from '../work.js';
+/** What changed between a source's current snapshot and its previous retained one. */
+export const getChanges = {
+    request: args => ({ ...sourceSelection(args), history: true }),
+    run: ({ scope, args, work }, view) => ({
+        data: retainedChanges(findSource(view, args.sourceId), args, scope, work),
+    }),
+};

package/dist/service/operations/get-inventory-health.d.ts

@@ -0,0 +1,3 @@
+import { type Operation } from '../context.js';
+/** Capture freshness and coverage per source, plus how much activity nobody declared. */
+export declare const getInventoryHealth: Operation;

package/dist/service/operations/get-inventory-health.js

@@ -0,0 +1,81 @@
+import { fail } from '../../common.js';
+import { MapQueryError } from '../../types.js';
+import { sourceSelection } from '../context.js';
+import { undeclaredCounts } from '../discovery.js';
+import { policyCoverageOf, policyRecords } from '../policy.js';
+import { freshness } from '../summaries.js';
+import { string } from '../work.js';
+/** Capture freshness and coverage per source, plus how much activity nobody declared. */
+export const getInventoryHealth = {
+    // Health reports policy coverage for the whole source: past the pair limit it reads
+    // unknown instead of failing the health answer.
+    request: args => ({ ...sourceSelection(args), policy: { optional: true } }),
+    async run({ scope, args, now, work, staleSeconds, read }, view) {
+        // Activity nobody declared, per source: a second, optional read. If it fails, is too
+        // large or runs out of time, health still answers and the count reads unknown.
+        const activity = new Map();
+        let activityUnknown = 'not_reported';
+        if (scope.allTeams && view.sources.length) {
+            const budget = work.remaining() - 50;
+            try {
+                if (budget <= 0)
+                    fail('MAP_TIMEOUT');
+                const found = await read({ ...sourceSelection(args), undeclared: true }, budget);
+                for (const source of found.sources)
+                    activity.set(source.id, source);
+            }
+            catch (error) {
+                const code = error instanceof MapQueryError ? error.code : 'MAP_UNAVAILABLE';
+                activityUnknown =
+                    code === 'MAP_TIMEOUT'
+                        ? 'read_timeout'
+                        : code === 'MAP_LIMIT_EXCEEDED'
+                            ? 'limit_exceeded'
+                            : 'read_unavailable';
+            }
+        }
+        const undeclaredActivity = (source) => {
+            if (!scope.allTeams)
+                return { status: 'not_visible', reason: 'all_teams_required' };
+            const counted = activity.get(source.id);
+            if (!counted?.current.undeclared)
+                return { status: 'unknown', reason: activityUnknown };
+            // Counted against a newer publication than the one this response describes.
+            if (counted.current.id !== source.current.id)
+                return { status: 'unknown', reason: 'publication_changed' };
+            return undeclaredCounts(source, counted.current.undeclared);
+        };
+        return {
+            data: {
+                sources: view.sources.map(source => {
+                    work.step();
+                    return {
+                        id: source.id,
+                        sourceId: source.sourceId,
+                        tenantId: source.tenantId,
+                        profile: source.profile,
+                        generatedAt: source.current.generatedAt,
+                        snapshotId: source.current.snapshotId,
+                        projectionId: source.current.id,
+                        ...freshness(source.current.generatedAt, now, staleSeconds),
+                        coverage: {
+                            ...Object.fromEntries(Object.entries(source.current.coverage)
+                                .filter(([component]) => component !== 'policy')
+                                .map(([component, status]) => {
+                                work.step();
+                                return [component, { ...status, ...freshness(status.observedAt, now, staleSeconds) }];
+                            })),
+                            policy: policyCoverageOf(source.current, policyRecords(source.current, work)),
+                        },
+                        undeclaredActivity: undeclaredActivity(source),
+                    };
+                }),
+                visibility: scope.allTeams ? 'enrolled_sources' : 'visible_agent_sources',
+                limitations: [
+                    'Collection freshness is separate from current execution authority.',
+                    'undeclaredActivity counts tasks and caller principals that ran through this executor and belong to no declared agent. It is shown to all-teams readers only, and says nothing about agents that do not use the guard.',
+                ],
+            },
+        };
+    },
+};