# The Asset Interchange and the Collector

The platform speaks one language, to one place: the Interchange. The Collector is the way in. It takes any form an
outside system sends (an event, a reading, a PDF, a spreadsheet, a video), keeps the original, and names what it is
with MissionSight's event types. The Interchange then sends each event down the paths its rules choose.

will also need our own ingestion intermediary to get ALL types of data: some weird system might send a PDF, some
might send an event."

**State, 7 November 2026: first slice, local only.** Everything runs on one machine. The Jira desk, the i3 CMMS and
the alert channels are stubs. Nothing at SFB is connected, and no outside service is called. This repo has no remote.

## The shape

```
 Outside systems                 Collector (POST /collect)             Interchange                        Products
 BHS PLCs, KONE, BMS, i3,  -->   store the original (sha256)    -->    rule path selection         -->    the twin's asset JSON,
 drones, phones, cameras,        verify the signature                  log, history, actions              the Exploders,
 "a weird system that            classify by data rules                alert (role, route, escalation)    Airfieldpath, Causeway
 sends a PDF"                    check against the catalogue           ticket (Jira adapter, stub)
      |                          de-duplicate, order                   work order (i3 adapter, stub,
      |                          bind the sensor to its target         after a person confirms)
 local relay unit                trap: triggers name events            analysis (predictions)
 (read, buffer, sign, forward)        |
                                 MissionSight: the event-type and sensor-type catalogue
```

**See the Fleet World** (`stellarview/walkthroughs/fleet-3d`) for the same path on the real infrastructure: the fleet's
own ingestion Lambda and its S3 lake, and MissionSight's Kinesis stream. `docs/architecture.md` maps each local part to
its AWS design.

## Run it

```bash
npm install
npm test            # 77 tests
npm run demo        # BHS, KONE, a policy PDF, an interval trend and the Jira round trip
npm start           # the Collector on 127.0.0.1:4720
```

`npm run demo` prints each stage of five runs and writes one evidence line per stage to `evidence/`:

1. **BHS.** The relay sends Baggage claim 1's state, error and blocked. It is stored and trapped as
   `baggage.carousel.blocked` about the carousel, from its photo-eye sensor. The `baggage-blocked` path is chosen,
   with the reasons. The alert goes to stub channels and is acknowledged. A stub Jira ticket opens. A work order is
   proposed, confirmed by a person and sent to simulated i3. The twin's `claim-1.json` shows it all.
2. **KONE.** Escalator 3 stops and becomes `vt.escalator.stopped`. It takes the same steps, and the ticket comes back
   from the stub desk as accepted.
3. **PDF.** A maintenance policy is dropped. It is stored with its text extracted and becomes a document event. A
   review ticket opens. Reading the rules out of it is designed (`docs/document-rules.md`).

4. **Interval.** Baggage claim 1's drive overheating alarm came every 19 days and now comes every 15 (example data).
   The threshold comes from the Mission Studio's export, the single source. While the row is not confirmed the run
   shows "threshold not confirmed: not firing" and `GET /thresholds` lists the gap. After a test confirmation (the
   Studio's SFB seed with that one row confirmed by hand), the next alarm is trapped as `prediction.repeat_interval.shortening`, with the numbers and the
   threshold's id, version, parameters and confirmer. The windows come from the threshold, never from defaults. Its path opens a ticket and proposes a work order.

5. **Jira round trip** (`npm run demo:jira`, on fixtures). A carousel alarm becomes a Jira issue linked to its JSM
   Assets object. A person approves it in Jira, and the work order goes to simulated i3. The completion comes back
   through the Interchange's contract, the AI hook is raised, and a person accepts before Jira closes. Each step is
   labelled fixture, simulated or real. See `docs/jira-hub.md`.

`rfp-demo.json` maps each RFP 2027-006 requirement this shows (REQ-SFB ids) to its command, its test and what it does
not show yet.

## The endpoints

| Call | Does |
| --- | --- |
| `POST /collect` | Takes JSON (one object or an array), multipart files, or any raw body. Header `x-source` names the sender. |
| `GET /collected[?status=]` | Every item: classified, unclassified, rejected or duplicate, with the reasons |
| `GET /collected/:id` | One item with every stage it passed |
| `GET /events`, `GET /deliveries` | Interchange events, and each listener's result for each |
| `GET /alerts`, `POST /alerts/:id/ack` | Alerts, and an acknowledgement `{ by, role }` |
| `GET /tickets`, `POST /tickets/:id/refresh` | Tickets, and reading one back from the desk |
| `GET /work-orders`, `POST /work-orders/:id/confirm` | Work orders; a person confirms or rejects `{ by, decision }` |
| `GET /confirmations`, `POST /confirmations/:id` | AI judgements waiting for a person |
| `GET /twin/:asset` | The asset's state for the twin |
| `GET /actions`, `GET /triggers`, `GET /lanes` | Path actions, trigger health, analysis lanes |
| `GET /thresholds`, `POST /thresholds/reload` | The Mission Studio export in use (project, write time, sha256), and each gap; re-read the local copy |
| `GET /documents`, `GET /loads[/:id]`, `GET /missionsight-stream` | Documents, sheet and ETL loads, MissionSight events for captures |
| `POST /tick` | Run the time triggers and escalations now |
| `GET /health` | What is configured and what is not |
| `POST /hooks/jira`, `POST /hooks/i3` | The Jira hub, when on: webhooks from Jira, events from i3 |
| `POST /hub/setup`, `POST /hub/accept/:key` | Make the JSM Assets schema; a person accepts and Jira closes |
| `GET /hub/evidence`, `/hub/parked`, `/hub/links`, `/hub/mappings` | Every hop, parked messages, links, mapping versions |
| `POST /hub/parked/:id/retry` | Resume a parked message |
| `GET /hub/ai-requests`, `POST /hub/ai-results/:id` | The AI hook |

## What is in the repo

| Path | Holds |
| --- | --- |
| `contracts/` | JSON schemas: asset, reading, event, work order, ticket, document (each with source, `read_at` and `validated_at`); alert rule, route, escalation, acknowledgement; path, trigger, pipeline, analysis rule, source, video capture, load template |
| `vendor/missionsight/` | MissionSight's catalogue and stream event schemas, copied with the commit they came from (`SOURCE.json`). Never edited here. |
| `vendor/mission-studio/` | The Mission Studio's `thresholds-export@1` schema, copied with its commit. Thresholds themselves are read from the Studio's export. The Studio is now MissionSight's Setup Studio, which keeps the schema in `contracts/studio/` and serves the export on port 4702. |
| `data/sources/` | One file per sender: signature, de-duplication, classification rules |
| `data/sensors/` | Sensors as assets: the device each is bound to, its target, the target's snapshot, its retention |
| `data/triggers/`, `data/paths/` | Trapping and rule path selection, as data |
| `data/alerts/`, `data/analysis/` | Who is told and how; the repeat-fault prediction |
| `data/assets/` | The local copy of SFB asset records the snapshots are refreshed from |
| `templates/` | Load templates: assets, rooms and areas, sensor points, maintenance policies, contacts and roles, work orders |
| `adapters/` | The Jira hub library (`adapters/jira`: credentials, transport, JSM Assets, issues, webhooks, the fixture site), the Simplify i3 boundary (`adapters/simplify-i3`), alert channels (stubs), ETL (i3, Allen-Bradley, BMS, templates) |
| `mappings/` | The hub's mappings as data: tags, types, rules and events, each with its schema in `contracts/mappings`, a version and a source |
| `src/hub/` | The hub's flows, rule evaluation and mapping loader |
| `prompts/ai/` | The AI hook's prompt files (`docs/ai-hook.md`) |
| `examples/demo.mjs` | The end-to-end demo |
| `tools/` | The relay simulator, the snapshot refresh, the template generator, the catalogue sync, the writing check |
| `docs/` | `architecture.md` (built and designed), `document-rules.md` (designed), `jira-hub.md`, `ai-hook.md` |

## The rules it keeps

From `missionsight/docs/consistency.md`:
- **No fallbacks.** An unconfigured key, a missing desk or an unbound sensor is shown as such, never filled in.
- **Contracts in the repo.** Every data file is checked against its contract when the service starts, and in the
  tests.
- **Binaries out of git.** Originals, generated templates and demo output live under `var/`, `evidence/` and
  `templates/out/`, all ignored.

- Nothing is dropped or guessed. Every item stays visible at `GET /collected` with its state and reason.
- AI never acts on its own. A judgement waits for a person, and so does every work order.

## Example data

schema is read), the BMS point names and the ETL fixtures (`test/fixtures/`, a made-up Acme County airport). The SFB
asset records come from the first-cut build, which is not verified. Every trigger limit and path timing is marked as
an example value until the owner's policy sets it.
