@x12i/map-store-client 0.1.3 → 0.1.5

package/README.md

@@ -36,4 +36,158 @@ import { fetchBootstrap, walkWorkingPages, mapFetch } from '@x12i/map-store-clie
 import { asRecord } from '@x12i/map-store-client/util';
 ```
 
-Subpath exports: `/util`, `/types`, `/errors`, `/products`, `/bagCatalog`, `/attackSurfaces`, `/packets`.
+Subpath exports: `/util`, `/types`, `/errors`, `/products`, `/bagCatalog`, `/attackSurfaces`, `/packets`, `/estate`.
+
+`queryFindings` and `fetchVulnerabilitiesBriefing` are exported from the package root. They are the two map-store routes that are POST queries rather than working products.
+
+## The `estate` entry
+
+`@x12i/map-store-client/estate` holds the reads that do not go through map-store: the Memorix content lists, the census and analytics records, the triage decisions, and the story pipeline. It takes the Memorix read client you build yourself, so it adds no dependency on `@x12i/memorix-client-api-client`.
+
+Drawing stories needs `@x12i/storyflowix` at version 1.2.0 or newer. It is an optional peer: install it when you import `estate`. The rest of the package does not use it.
+
+```ts
+import { createMemorixReadClient } from '@x12i/memorix-client-api-client';
+import { listContent, PREDICTED_ATTACK_LIST, isPredictedAttack } from '@x12i/map-store-client/estate';
+
+const memorix = createMemorixReadClient({
+  baseUrl: 'http://memorix-client.invalid', // rewritten onto the /memorix-client proxy
+  orgId: 'tgi',
+  agentIds: ['network-synapix'],
+  caller: 'your-app',
+});
+
+// One list per object type the contract declares, markdown included, up to 20 pages of 200.
+const attacks = (
+  await Promise.all(
+    PREDICTED_ATTACK_LIST.objectTypes.map((objectType) =>
+      listContent(memorix.data, { objectType, contentType: 'predicted-attack', includeMarkdown: true })
+    )
+  )
+).flat().filter((row) => isPredictedAttack(row.data));
+```
+
+The browser reaches the Memorix client API through your proxy at `/memorix-client`, with `x-memorix-org-id`, `x-memorix-agent-ids`, and `x-memorix-caller`. Story functions run through your proxy at `/skill-api` (`runStoryFunction`, agent `network-synapix`). Neither call goes to Memorix directly.
+
+## What each page reads
+
+Pins (`snapshotSetId`, `analysisSnapshotId`) come from `fetchBootstrap` and are passed as `expectedPair` on walks. They are never sent back as URL pins. A working product that pages returns `pageVariants`; `walkWorkingPages` fetches each of them.
+
+### Once per session, shared by every page
+
+| Read | Call |
+|---|---|
+| `GET /map-store/v1/health` | `fetchHealth` |
+| `GET /map-store/v1/bootstrap` | `fetchBootstrap` |
+| `working/estate-object-inventory`, all pages | `walkWorkingPages('estate-object-inventory', parseInventoryObject)` |
+| `working/object-pre-ai-context`, all pages | `walkWorkingPages('object-pre-ai-context', …)` |
+| `working/findings-query`, entry variant `open-vuln` | `walkWorkingPages('findings-query', …)`. If no row carries a CVE, fall back to `investigation-assessment` |
+| `working/cve-catalog`, all pages | `walkWorkingPages('cve-catalog', …)` |
+| `working/source-capability` | `fetchWorkingProduct('source-capability')` |
+| `working/object-classification-census` | `fetchWorkingProduct('object-classification-census')` |
+| `working/attack-surfaces` and `working/vpn-sites` | `fetchAttackSurfacesIndex`, `fetchVpnSitesIndex` |
+| `working/open-questions` | `fetchWorkingProduct('open-questions')` |
+| `working/known-unknowns-summary`, falling back to `known-unknowns` | `fetchWorkingProduct` |
+| `working/reachability-claims-summary` | `fetchWorkingProduct('reachability-claims-summary')` |
+| `working/attack-path-assessments` | `fetchWorkingProduct('attack-path-assessments')` |
+| `working/alerts-query?variant=all` and `?variant=relevant` | `fetchWorkingProduct('alerts-query', 'all' \| 'relevant')` |
+| `working/alerts-briefing` | `fetchWorkingProduct('alerts-briefing')` |
+| `working/live-bootstrap` | `fetchLiveBootstrap` |
+| `working/prospective-capability` | `fetchWorkingProduct('prospective-capability')` |
+| `security-map` / `estate-analytics` / `working/estate-analytics`, discriminator `publication` | `readEstateAnalytics` |
+| Connector census | `readSourceCensus` |
+| Ranked CVE hubs | `fetchVulnerabilitiesBriefing` |
+
+When `estateAnalyticsSuppliesTallies` is false, the triage counts are not on that record. Count them from `TRIAGE_TALLY_LISTS` with `listContent`: `finding` / `triage` (up to 400 pages) and `endpoint-asset` / `triage` (up to 20).
+
+### Data sources
+
+**Asset inventory** (`/assets`, plus `/assets/vulnerable`, `/endpoints`, `/identified`, `/unidentified`)
+
+- The walked inventory, identities, and findings, and the CVE catalog for the severity dots.
+- `loadTier0Census(data, 'asset')` — `security-map` / `tier0-analytics` / `working/asset-census`, discriminator `asset-census`.
+- `listContent` of `endpoint-asset` / `triage`.
+- A drill-down by decision uses `loadAssetDecisionIds` instead of the full list. It filters `data.decisionType=asset-triage` plus `data.urgency`, `data.decision=NOT_APPLICABLE`, or `data.assessmentState`. `loadAssetUrgencies` maps each asset to its urgency.
+- `walkWorkingPages('attack-path-assessments', …)` for the zone reach tier. A row's `toZoneId` plus a `hypothesis` containing "deny" marks the zone cleared; any other hypothesis marks it possible.
+
+**Networks** (`/networks`)
+
+- Subnets and zones are derived from the walked inventory. No separate read.
+- The attack-surfaces index, the VPN-sites index, and `reachability-claims-summary`.
+- `readEstateAnalytics`.
+
+**Vulnerability catalog** (`/vulnerabilities`, plus `/cves`, `/kev`, `/exploitable`, `/findings`)
+
+- The walked findings joined to the inventory, the CVE catalog, and `fetchVulnerabilitiesBriefing`.
+- `queryFindings` for scanner severity, CVSS, KEV, EPSS, and the vendor description. Join on finding id and on CVE id.
+- `loadTier0Census(data, 'vulnerability')` — `working/vulnerability-census`.
+- `listContent` of `finding` / `triage`, up to 120 pages.
+- One finding's decision: `listRecordContent` of `finding` / `triage` with `discriminator: { field: 'decisionType', value: 'finding-triage' }`. `triageInstance(objectType)` names the instance.
+- The CVE panel's analyses: `listContent` of `finding` / `analysis` filtered by `data.cveId`.
+- A verdict line: `listRecordContent` of `finding` / `verdict-reason` for that record id, with markdown.
+
+**Recent alerts** (`/alerts`)
+
+- `source-capability`, `alerts-query` (`all` and `relevant`), and `alerts-briefing`.
+- The walked inventory, for the asset names.
+
+### Analysis
+
+Both pages list one content type on every object type that declares it (`PREDICTED_ATTACK_LIST`, `MITIGATION_LIST`), with markdown, up to 20 pages of 200.
+
+**Predicted attacks** (`/predicted-attacks`)
+
+- `listContent` of `predicted-attack` on `finding`, `endpoint-asset`, `alert`, `network-device`, and `network-zone`. Keep a row when `isPredictedAttack` is true (`data.predictionType` is `finding-attack`, `asset-attack`, `alert-attack`, `device-attack`, or `zone-attack`).
+- Fields read: `summary`, `scenarioSupport`, `score`, `asOf`, and `actions[]` (`action`, `phase`, `technique`, `assets`, `controls`, `chance`). `steps[]` is the fallback when no action names a technique.
+
+**Mitigations** (`/mitigations`)
+
+- `listContent` of `mitigation` on `finding`, `endpoint-asset`, `alert`, and `network-zone`. Keep a row when `isMitigationPlan` is true (`data.mitigationType` is `response-plan` and `data.plan.schemaVersion` is `response-plan/v1`).
+- Fields read: `planStatus`, `summary`, `plan.subject.displayName`, and `plan.recommendations[]` (`title`, `readiness`, `conditions[].statement`, `steps`, `proposedOwnerRole`, `why`, `targetEffect`).
+
+**Subject names.** `inventoryDisplayName(data, objectType, recordId)` reads `data.displayName` from that subject's `inventory` row.
+
+**The diagram.** `predictionStepsFrom(row)` reads the steps, and `predictionDiagram(source)` builds the Storyflowix input. Every step carrying a technique id uses the `attack-path` template. Otherwise it uses `predicted-attack`, which `predictedAttackReady()` checks for in the installed Storyflowix. No steps, or `scenarioSupport` of `INSUFFICIENT_EVIDENCE`, produces the withheld block. No further request is made.
+
+### Exposure
+
+**Attack surfaces** (`/attack-surfaces/entries`, `/attack-surfaces/shared`)
+
+- `fetchAttackSurfacesIndex`, then `fetchAttackSurfaceDossier(surfaceId)` per surface. Read `epistemicBuckets`, `destZones`, `instances`, and `honesty`.
+
+**Exploitability assessments** (`/epa`)
+
+- `walkWorkingPages('object-exploitability-assessments', …)`.
+- `fetchBootstrap().assessmentCoverage` and `loadTier0Census(data, 'asset')`.
+
+**VPN sites** (`/vpn-sites/sites`, `/vpn-sites/shared`)
+
+- `fetchVpnSitesIndex`, then `fetchVpnSiteDossier(siteId)` per site. Read `peerPublicIp`, `remoteInnerOrigins`, `localInnerSelectors`, `nativeAcceptDestZones`, and `epistemicBuckets`.
+
+**Reachability** (`/reachability`)
+
+- `reachability-claims-summary`, the walked inventory, and `loadTier0Census(data, 'asset')`.
+- `listContent` of `endpoint-asset` / `reachability-analysis`.
+
+The estate census board, where a page shows one, is `loadTier0Census(data, 'estate')` — `working/estate-census`.
+
+### Opening one record
+
+**Context diagram.** An asset reads `listRecordContent` of `triage` with `triageInstance(objectType)`, and of `analysis`, using the `asset-exposure` and `zone-candidate` rows. A finding reads `finding` / `triage` with `finding-triage`, and `finding` / `analysis`, using the `vulnerability` or `detection` row.
+
+**Story.**
+
+1. `loadStoryTabs(catalog, objectType)` — `GET /api/v1/object-types/{type}` for `functions[]`, and `GET /api/v1/object-types/{type}/content-types/story` for the presentation labels.
+2. `readStoredStory(data, objectType, recordId, template)` — the stored `story` row. Render `input` with Storyflowix and show `text`, `facts`, and `gaps`.
+3. When nothing is stored, `runStoryFunction(functionId, objectType, recordId)` — `POST /skill-api/api/v1/agent-functions/agents/network-synapix/functions/{id}/run` with `{ objectType, recordId }`. Render `result.storyInput`.
+4. When the run stops, `loadRecordContents(catalog, objectType, recordId)` then `buildLocalStory(template, objectType, contents)`. One `listRecords` call with `representation: 'both'`.
+
+`declaringObjectTypes(contentType)` and `skillsContentTypes(objectType)` are the contract behind the lists: which object types declare which content types, and which discriminator values a row may carry. `requiredDiscriminator` reads the installed pack and names the instance a single-record read must send, so the API does not reject it with `READ_DISCRIMINATOR_REQUIRED`.
+
+### Read states
+
+`classifyReadError` and `isPlaceholderRecord` sort a Memorix answer into `declared-empty` (404), `undeclared` (`400 ROUTE_UNKNOWN_CONTENT_TYPE`), `placeholder` (a body whose `disposition` is `empty-from-frozen-bag` or `unavailable`), or `error`. `UNPUBLISHED_BY_AGENT` is the sentence for the last two that are not failures.
+
+`readContentResult`, `listContentResult`, `readEstateAnalyticsResult`, `loadTier0CensusResult`, and `readStoredStoryResult` return `{ state, data }`. The older functions still return the row or `null`. A placeholder land is `null` from those, not a rollup. `verdictReasonView(rows, verdict)` is the finding-drawer text: summary, evidence, and gaps, with a failed skill run dropped.
+
+`CONSUMER_MANIFEST` is every `{ objectType, contentType }` these pages read, including `finding` / `verdict-reason`, `story`, and `tier0-analytics`. Compare it with the installed pack to list what the agent has not declared.

package/dist/estate/analytics.d.ts

@@ -0,0 +1,50 @@
+/**
+ * The materialized estate rollup, and the connector census.
+ * Both are single Memorix reads. Neither is a working product.
+ */
+import type { EstateAnalyticsApi, EstateData } from './client';
+import { type ReadResult } from './readState';
+export declare const ESTATE_ANALYTICS_TARGET: {
+    readonly objectType: "security-map";
+    readonly contentType: "estate-analytics";
+    readonly recordId: "working/estate-analytics";
+    readonly discriminatorValue: "publication";
+};
+/**
+ * `data` of `working/estate-analytics`.
+ * `placeholder` is a land such as `empty-from-frozen-bag`: the address is taken and the rollup is not published.
+ * `declared-empty` is a 404. `undeclared` means the pack does not register the content type.
+ */
+export declare function readEstateAnalyticsResult(client: EstateData, signal?: AbortSignal): Promise<ReadResult<Record<string, unknown>>>;
+/**
+ * `data` of `working/estate-analytics`.
+ * Null when the record is missing, the content type is not registered, or the
+ * body is a placeholder land. Any other error is thrown.
+ * Use {@link readEstateAnalyticsResult} to tell those apart.
+ */
+export declare function readEstateAnalytics(client: EstateData, signal?: AbortSignal): Promise<Record<string, unknown> | null>;
+/**
+ * True when the estate-analytics record already carries the triage counts:
+ * finding decisions, asset decisions, priority bands, findings triaged,
+ * and both exploitability measures.
+ * When this is false, count them from the triage lists instead
+ * (`finding` / `triage` and `endpoint-asset` / `triage`). Nothing else is walked.
+ */
+export declare function estateAnalyticsSuppliesTallies(raw: unknown): boolean;
+/** Lists to count when {@link estateAnalyticsSuppliesTallies} is false. */
+export declare const TRIAGE_TALLY_LISTS: readonly [{
+    readonly objectType: "finding";
+    readonly contentType: "triage";
+    readonly maxPages: 400;
+}, {
+    readonly objectType: "endpoint-asset";
+    readonly contentType: "triage";
+    readonly maxPages: 20;
+}];
+/**
+ * Connector census from `analytics.sourceCensus`.
+ * Null when the call fails or the body has no `status` and `subjects`.
+ * A `status` other than `live` is returned as-is and is not ready to render.
+ */
+export declare function readSourceCensus(analytics: EstateAnalyticsApi, signal?: AbortSignal): Promise<Record<string, unknown> | null>;
+//# sourceMappingURL=analytics.d.ts.map

package/dist/estate/analytics.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"analytics.d.ts","sourceRoot":"","sources":["../../src/estate/analytics.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAGH,OAAO,KAAK,EAAE,kBAAkB,EAAE,UAAU,EAAE,MAAM,UAAU,CAAC;AAE/D,OAAO,EAA0C,KAAK,UAAU,EAAE,MAAM,aAAa,CAAC;AAEtF,eAAO,MAAM,uBAAuB;;;;;CAK1B,CAAC;AAEX;;;;GAIG;AACH,wBAAsB,yBAAyB,CAC7C,MAAM,EAAE,UAAU,EAClB,MAAM,CAAC,EAAE,WAAW,GACnB,OAAO,CAAC,UAAU,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC,CAc9C;AAED;;;;;GAKG;AACH,wBAAsB,mBAAmB,CACvC,MAAM,EAAE,UAAU,EAClB,MAAM,CAAC,EAAE,WAAW,GACnB,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC,CAIzC;AAsBD;;;;;;GAMG;AACH,wBAAgB,8BAA8B,CAAC,GAAG,EAAE,OAAO,GAAG,OAAO,CAsBpE;AAED,2EAA2E;AAC3E,eAAO,MAAM,kBAAkB;;;;;;;;EAGrB,CAAC;AAEX;;;;GAIG;AACH,wBAAsB,gBAAgB,CACpC,SAAS,EAAE,kBAAkB,EAC7B,MAAM,CAAC,EAAE,WAAW,GACnB,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC,CASzC"}

package/dist/estate/analytics.js

@@ -0,0 +1,128 @@
+/**
+ * The materialized estate rollup, and the connector census.
+ * Both are single Memorix reads. Neither is a working product.
+ */
+import { asRecord } from '../util';
+import { contentData } from './content';
+import { classifyReadError, isPlaceholderRecord } from './readState';
+export const ESTATE_ANALYTICS_TARGET = {
+    objectType: 'security-map',
+    contentType: 'estate-analytics',
+    recordId: 'working/estate-analytics',
+    discriminatorValue: 'publication',
+};
+/**
+ * `data` of `working/estate-analytics`.
+ * `placeholder` is a land such as `empty-from-frozen-bag`: the address is taken and the rollup is not published.
+ * `declared-empty` is a 404. `undeclared` means the pack does not register the content type.
+ */
+export async function readEstateAnalyticsResult(client, signal) {
+    if (signal?.aborted)
+        return { state: 'declared-empty', data: null };
+    try {
+        const page = await client.getContent({ ...ESTATE_ANALYTICS_TARGET });
+        if (signal?.aborted)
+            return { state: 'declared-empty', data: null };
+        const data = contentData(page);
+        if (!data)
+            return { state: 'declared-empty', data: null };
+        if (isPlaceholderRecord(data))
+            return { state: 'placeholder', data: null };
+        return { state: 'ready', data };
+    }
+    catch (err) {
+        const kind = classifyReadError(err);
+        if (kind === 'error')
+            return { state: 'error', data: null, error: err };
+        return { state: kind, data: null };
+    }
+}
+/**
+ * `data` of `working/estate-analytics`.
+ * Null when the record is missing, the content type is not registered, or the
+ * body is a placeholder land. Any other error is thrown.
+ * Use {@link readEstateAnalyticsResult} to tell those apart.
+ */
+export async function readEstateAnalytics(client, signal) {
+    const result = await readEstateAnalyticsResult(client, signal);
+    if (result.state === 'error')
+        throw result.error;
+    return result.data;
+}
+const TRIAGE_DECISIONS = ['FIX_NOW', 'PATCH_NOW', 'MITIGATE', 'ACCEPT_RISK'];
+function readCount(leaf) {
+    if (typeof leaf === 'number' && Number.isFinite(leaf))
+        return leaf;
+    const rec = asRecord(leaf);
+    if (!rec || rec.produced === false)
+        return null;
+    const raw = rec.value ?? rec.count;
+    return typeof raw === 'number' && Number.isFinite(raw) ? raw : null;
+}
+function metricProduced(root, key) {
+    if (!root)
+        return false;
+    const direct = asRecord(root[key]);
+    if (direct?.produced === true && typeof direct.value === 'number')
+        return true;
+    const [section, name] = key.split('.');
+    const bag = asRecord(root[section ?? '']);
+    const nested = name ? asRecord(bag?.[name]) : null;
+    return nested?.produced === true && typeof nested.value === 'number';
+}
+/**
+ * True when the estate-analytics record already carries the triage counts:
+ * finding decisions, asset decisions, priority bands, findings triaged,
+ * and both exploitability measures.
+ * When this is false, count them from the triage lists instead
+ * (`finding` / `triage` and `endpoint-asset` / `triage`). Nothing else is walked.
+ */
+export function estateAnalyticsSuppliesTallies(raw) {
+    const top = asRecord(raw);
+    const groups = asRecord(top?.groups);
+    if (!top || !groups)
+        return false;
+    const bagReady = (group) => {
+        if (!group || group.produced === false)
+            return false;
+        const bag = asRecord(group.buckets) ?? group;
+        return TRIAGE_DECISIONS.every((code) => readCount(bag[code] ?? bag[code.toLowerCase()]) != null);
+    };
+    if (!bagReady(asRecord(groups.findingDecisions)) || !bagReady(asRecord(groups.assetDecisions)))
+        return false;
+    const priority = asRecord(groups.priorityBands);
+    if (!priority || priority.produced === false)
+        return false;
+    if (readCount(priority.high) == null || readCount(priority.medium) == null || readCount(priority.low) == null) {
+        return false;
+    }
+    const measures = asRecord(top.measures);
+    return ((metricProduced(measures, 'exploitability.reviewed') || metricProduced(top, 'exploitability.reviewed')) &&
+        (metricProduced(measures, 'exploitability.highOrCritical') ||
+            metricProduced(top, 'exploitability.highOrCritical')) &&
+        (metricProduced(measures, 'planned.findingsTriaged') || metricProduced(top, 'planned.findingsTriaged')));
+}
+/** Lists to count when {@link estateAnalyticsSuppliesTallies} is false. */
+export const TRIAGE_TALLY_LISTS = [
+    { objectType: 'finding', contentType: 'triage', maxPages: 400 },
+    { objectType: 'endpoint-asset', contentType: 'triage', maxPages: 20 },
+];
+/**
+ * Connector census from `analytics.sourceCensus`.
+ * Null when the call fails or the body has no `status` and `subjects`.
+ * A `status` other than `live` is returned as-is and is not ready to render.
+ */
+export async function readSourceCensus(analytics, signal) {
+    try {
+        const body = asRecord(await analytics.sourceCensus());
+        if (signal?.aborted)
+            return null;
+        if (!body || typeof body.status !== 'string' || !Array.isArray(body.subjects))
+            return null;
+        return body;
+    }
+    catch {
+        return null;
+    }
+}
+//# sourceMappingURL=analytics.js.map

package/dist/estate/analytics.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"analytics.js","sourceRoot":"","sources":["../../src/estate/analytics.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAC;AAEnC,OAAO,EAAE,WAAW,EAAE,MAAM,WAAW,CAAC;AACxC,OAAO,EAAE,iBAAiB,EAAE,mBAAmB,EAAmB,MAAM,aAAa,CAAC;AAEtF,MAAM,CAAC,MAAM,uBAAuB,GAAG;IACrC,UAAU,EAAE,cAAc;IAC1B,WAAW,EAAE,kBAAkB;IAC/B,QAAQ,EAAE,0BAA0B;IACpC,kBAAkB,EAAE,aAAa;CACzB,CAAC;AAEX;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,yBAAyB,CAC7C,MAAkB,EAClB,MAAoB;IAEpB,IAAI,MAAM,EAAE,OAAO;QAAE,OAAO,EAAE,KAAK,EAAE,gBAAgB,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC;IACpE,IAAI,CAAC;QACH,MAAM,IAAI,GAAG,MAAM,MAAM,CAAC,UAAU,CAAC,EAAE,GAAG,uBAAuB,EAAE,CAAC,CAAC;QACrE,IAAI,MAAM,EAAE,OAAO;YAAE,OAAO,EAAE,KAAK,EAAE,gBAAgB,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC;QACpE,MAAM,IAAI,GAAG,WAAW,CAAC,IAAI,CAAC,CAAC;QAC/B,IAAI,CAAC,IAAI;YAAE,OAAO,EAAE,KAAK,EAAE,gBAAgB,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC;QAC1D,IAAI,mBAAmB,CAAC,IAAI,CAAC;YAAE,OAAO,EAAE,KAAK,EAAE,aAAa,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC;QAC3E,OAAO,EAAE,KAAK,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC;IAClC,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,MAAM,IAAI,GAAG,iBAAiB,CAAC,GAAG,CAAC,CAAC;QACpC,IAAI,IAAI,KAAK,OAAO;YAAE,OAAO,EAAE,KAAK,EAAE,OAAO,EAAE,IAAI,EAAE,IAAI,EAAE,KAAK,EAAE,GAAG,EAAE,CAAC;QACxE,OAAO,EAAE,KAAK,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC;IACrC,CAAC;AACH,CAAC;AAED;;;;;GAKG;AACH,MAAM,CAAC,KAAK,UAAU,mBAAmB,CACvC,MAAkB,EAClB,MAAoB;IAEpB,MAAM,MAAM,GAAG,MAAM,yBAAyB,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC/D,IAAI,MAAM,CAAC,KAAK,KAAK,OAAO;QAAE,MAAM,MAAM,CAAC,KAAK,CAAC;IACjD,OAAO,MAAM,CAAC,IAAI,CAAC;AACrB,CAAC;AAED,MAAM,gBAAgB,GAAG,CAAC,SAAS,EAAE,WAAW,EAAE,UAAU,EAAE,aAAa,CAAC,CAAC;AAE7E,SAAS,SAAS,CAAC,IAAa;IAC9B,IAAI,OAAO,IAAI,KAAK,QAAQ,IAAI,MAAM,CAAC,QAAQ,CAAC,IAAI,CAAC;QAAE,OAAO,IAAI,CAAC;IACnE,MAAM,GAAG,GAAG,QAAQ,CAAC,IAAI,CAAC,CAAC;IAC3B,IAAI,CAAC,GAAG,IAAI,GAAG,CAAC,QAAQ,KAAK,KAAK;QAAE,OAAO,IAAI,CAAC;IAChD,MAAM,GAAG,GAAG,GAAG,CAAC,KAAK,IAAI,GAAG,CAAC,KAAK,CAAC;IACnC,OAAO,OAAO,GAAG,KAAK,QAAQ,IAAI,MAAM,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC;AACtE,CAAC;AAED,SAAS,cAAc,CAAC,IAAoC,EAAE,GAAW;IACvE,IAAI,CAAC,IAAI;QAAE,OAAO,KAAK,CAAC;IACxB,MAAM,MAAM,GAAG,QAAQ,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC;IACnC,IAAI,MAAM,EAAE,QAAQ,KAAK,IAAI,IAAI,OAAO,MAAM,CAAC,KAAK,KAAK,QAAQ;QAAE,OAAO,IAAI,CAAC;IAC/E,MAAM,CAAC,OAAO,EAAE,IAAI,CAAC,GAAG,GAAG,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;IACvC,MAAM,GAAG,GAAG,QAAQ,CAAC,IAAI,CAAC,OAAO,IAAI,EAAE,CAAC,CAAC,CAAC;IAC1C,MAAM,MAAM,GAAG,IAAI,CAAC,CAAC,CAAC,QAAQ,CAAC,GAAG,EAAE,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC;IACnD,OAAO,MAAM,EAAE,QAAQ,KAAK,IAAI,IAAI,OAAO,MAAM,CAAC,KAAK,KAAK,QAAQ,CAAC;AACvE,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,8BAA8B,CAAC,GAAY;IACzD,MAAM,GAAG,GAAG,QAAQ,CAAC,GAAG,CAAC,CAAC;IAC1B,MAAM,MAAM,GAAG,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC,CAAC;IACrC,IAAI,CAAC,GAAG,IAAI,CAAC,MAAM;QAAE,OAAO,KAAK,CAAC;IAClC,MAAM,QAAQ,GAAG,CAAC,KAAqC,EAAW,EAAE;QAClE,IAAI,CAAC,KAAK,IAAI,KAAK,CAAC,QAAQ,KAAK,KAAK;YAAE,OAAO,KAAK,CAAC;QACrD,MAAM,GAAG,GAAG,QAAQ,CAAC,KAAK,CAAC,OAAO,CAAC,IAAI,KAAK,CAAC;QAC7C,OAAO,gBAAgB,CAAC,KAAK,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,SAAS,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,GAAG,CAAC,IAAI,CAAC,WAAW,EAAE,CAAC,CAAC,IAAI,IAAI,CAAC,CAAC;IACnG,CAAC,CAAC;IACF,IAAI,CAAC,QAAQ,CAAC,QAAQ,CAAC,MAAM,CAAC,gBAAgB,CAAC,CAAC,IAAI,CAAC,QAAQ,CAAC,QAAQ,CAAC,MAAM,CAAC,cAAc,CAAC,CAAC;QAAE,OAAO,KAAK,CAAC;IAC7G,MAAM,QAAQ,GAAG,QAAQ,CAAC,MAAM,CAAC,aAAa,CAAC,CAAC;IAChD,IAAI,CAAC,QAAQ,IAAI,QAAQ,CAAC,QAAQ,KAAK,KAAK;QAAE,OAAO,KAAK,CAAC;IAC3D,IAAI,SAAS,CAAC,QAAQ,CAAC,IAAI,CAAC,IAAI,IAAI,IAAI,SAAS,CAAC,QAAQ,CAAC,MAAM,CAAC,IAAI,IAAI,IAAI,SAAS,CAAC,QAAQ,CAAC,GAAG,CAAC,IAAI,IAAI,EAAE,CAAC;QAC9G,OAAO,KAAK,CAAC;IACf,CAAC;IACD,MAAM,QAAQ,GAAG,QAAQ,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;IACxC,OAAO,CACL,CAAC,cAAc,CAAC,QAAQ,EAAE,yBAAyB,CAAC,IAAI,cAAc,CAAC,GAAG,EAAE,yBAAyB,CAAC,CAAC;QACvG,CAAC,cAAc,CAAC,QAAQ,EAAE,+BAA+B,CAAC;YACxD,cAAc,CAAC,GAAG,EAAE,+BAA+B,CAAC,CAAC;QACvD,CAAC,cAAc,CAAC,QAAQ,EAAE,yBAAyB,CAAC,IAAI,cAAc,CAAC,GAAG,EAAE,yBAAyB,CAAC,CAAC,CACxG,CAAC;AACJ,CAAC;AAED,2EAA2E;AAC3E,MAAM,CAAC,MAAM,kBAAkB,GAAG;IAChC,EAAE,UAAU,EAAE,SAAS,EAAE,WAAW,EAAE,QAAQ,EAAE,QAAQ,EAAE,GAAG,EAAE;IAC/D,EAAE,UAAU,EAAE,gBAAgB,EAAE,WAAW,EAAE,QAAQ,EAAE,QAAQ,EAAE,EAAE,EAAE;CAC7D,CAAC;AAEX;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,gBAAgB,CACpC,SAA6B,EAC7B,MAAoB;IAEpB,IAAI,CAAC;QACH,MAAM,IAAI,GAAG,QAAQ,CAAC,MAAM,SAAS,CAAC,YAAY,EAAE,CAAC,CAAC;QACtD,IAAI,MAAM,EAAE,OAAO;YAAE,OAAO,IAAI,CAAC;QACjC,IAAI,CAAC,IAAI,IAAI,OAAO,IAAI,CAAC,MAAM,KAAK,QAAQ,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC,QAAQ,CAAC;YAAE,OAAO,IAAI,CAAC;QAC3F,OAAO,IAAI,CAAC;IACd,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,IAAI,CAAC;IACd,CAAC;AACH,CAAC"}

package/dist/estate/census.d.ts

@@ -0,0 +1,123 @@
+/**
+ * Tier-0 census records. Three processes count published lander rows and each
+ * save one content record. They do not read AI products. They are not
+ * `estate-analytics` and they are not a bag total.
+ *
+ * One GET per board, after `working/bootstrap` has pinned the session:
+ * `security-map` / `tier0-analytics` / `working/{vulnerability,asset,estate}-census`.
+ * `data.kind` selects the record.
+ *
+ * `produced: true` and `value: 0` is a finished empty count.
+ * `produced: false` and `value: 0` means that source was not read.
+ * A missing field is the bucket `absent`. A missing KEV flag is `absent`, not `false`.
+ */
+import type { EstateData } from './client';
+import { type ReadResult } from './readState';
+export type Tier0Metric = {
+    value: number;
+    produced: boolean;
+};
+export type MetricMap = Record<string, Tier0Metric>;
+export type VulnerabilityCensusRow = {
+    id: string;
+    cveId: string | null;
+    label: string | null;
+    affectedAssets: number | null;
+    findings: number | null;
+};
+export type AssetCensusRow = {
+    id: string;
+    label: string | null;
+    findings: number | null;
+    distinctCves: number | null;
+};
+export type VulnerabilityCensus = {
+    kind: 'vulnerability-census';
+    totals: {
+        findings: Tier0Metric;
+        vulnerabilities: Tier0Metric;
+        distinctCves: Tier0Metric;
+    };
+    rows: VulnerabilityCensusRow[];
+    groups: Record<string, MetricMap>;
+};
+export type AssetCensus = {
+    kind: 'asset-census';
+    totals: {
+        assets: Tier0Metric;
+        findings: Tier0Metric;
+    };
+    rows: AssetCensusRow[];
+    groups: Record<string, MetricMap>;
+};
+export type EstateCensus = {
+    kind: 'estate-census';
+    totals: {
+        subjects: {
+            endpointAssets: Tier0Metric;
+            findings: Tier0Metric;
+            alerts: Tier0Metric;
+            zones: Tier0Metric;
+            devices: Tier0Metric;
+            unresolvedSubjects: Tier0Metric;
+        };
+        bags: {
+            hypothesizedPaths: Tier0Metric;
+            reachabilityClaims: Tier0Metric;
+        };
+    };
+    rows: readonly [];
+    groups: Record<string, MetricMap>;
+};
+export type Tier0Census = VulnerabilityCensus | AssetCensus | EstateCensus;
+export declare const EMPTY_VULNERABILITY_ROWS: VulnerabilityCensusRow[];
+export declare const EMPTY_ASSET_ROWS: AssetCensusRow[];
+export type Tier0BoardId = 'vulnerability' | 'asset' | 'estate';
+export declare const TIER0_TARGETS: {
+    readonly vulnerability: {
+        readonly recordId: "working/vulnerability-census";
+        readonly kind: "vulnerability-census";
+    };
+    readonly asset: {
+        readonly recordId: "working/asset-census";
+        readonly kind: "asset-census";
+    };
+    readonly estate: {
+        readonly recordId: "working/estate-census";
+        readonly kind: "estate-census";
+    };
+};
+/** A figure the census has not produced is absent, not zero. */
+export declare function tier0Value(metric: Tier0Metric | undefined): number | null;
+export declare function publishedCount(value: number | null | undefined): string;
+/**
+ * List figure. A loaded census uses its own number, including a finished `0`.
+ * A missing row on a loaded census is unavailable.
+ * Before that document exists, the lander figure keeps the column from going blank.
+ */
+export declare function censusOrLander(censusReady: boolean, censusRow: object | null, censusValue: number | null | undefined, landerValue: number | null | undefined): number | null;
+/** Parse one census body. A mismatched `data.kind` is not that board's record. */
+export declare function parseTier0Census(page: unknown, kind: Tier0Census['kind']): Tier0Census | null;
+/**
+ * One client-API read of `security-map` / `tier0-analytics`.
+ * `declared-empty` is a missing record. `undeclared` means the content type is not registered.
+ * `placeholder` is a land with no census. A transport failure is `error` and is not logged here.
+ */
+export declare function loadTier0CensusResult(client: EstateData, board: Tier0BoardId, signal?: AbortSignal): Promise<ReadResult<Tier0Census>>;
+/**
+ * One client-API read of `security-map` / `tier0-analytics`.
+ * A missing record, an unregistered content type, a placeholder land, or a failed read yields null.
+ * Use {@link loadTier0CensusResult} to tell those apart.
+ */
+export declare function loadTier0Census(client: EstateData, board: Tier0BoardId, signal?: AbortSignal): Promise<Tier0Census | null>;
+/** Dialog lookup. `rows[].id` is the lander record id. */
+export declare function censusEntryById<T extends {
+    id: string;
+}>(rows: readonly T[], id: string): T | null;
+/**
+ * CVE dialog join. The panel's key is the CVE text. Use the lander id when that
+ * id is the CVE, otherwise the single census row that publishes this `cveId`.
+ * Several rows for one CVE stay unresolved here. Each dialog still matches by id.
+ */
+export declare function vulnerabilityEntryForCve(rows: readonly VulnerabilityCensusRow[], cveId: string): VulnerabilityCensusRow | null;
+//# sourceMappingURL=census.d.ts.map

package/dist/estate/census.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"census.d.ts","sourceRoot":"","sources":["../../src/estate/census.ts"],"names":[],"mappings":"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"}