iridium-db 0.2.0

A high-performance vector-graph hybrid storage and indexing engine
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131

# single-node service runbook

Minimal operator runbook for the first Iridium service candidate surface.

This is intentionally narrow. It is for local evaluation and single-node operator checks, not a hardened production deployment.

For the packaging-oriented install view of the same surface, see `docs/service_install.md`.

## prerequisites

- Build the CLI:

```sh
cargo build --bin ir
```

- Choose a local data root. The service commands expect `--data` to point at the parent of the `data/` directory they will use.

Example layout:

```text
/tmp/iridium-service-root/
└── data/
```

## recommended settings

Use the current validated service-candidate settings:

```text
listen_address=127.0.0.1:7001
telemetry_endpoint=stdout
tls_mode=operator-optional
admin_token=local-dev
max_requests=16
```

These settings match the verified Sprint 4 operator surface and artifact scripts.

## seed a local fixture

```sh
rm -rf /tmp/iridium-service-root
mkdir -p /tmp/iridium-service-root
cargo run --quiet --bin ir -- --data /tmp/iridium-service-root ingest-node 1 1 2,3
```

## validate the config

```sh
cargo run --quiet --bin ir -- \
  --data /tmp/iridium-service-root \
  service-validate \
  --listen 127.0.0.1:7001 \
  --telemetry-endpoint stdout \
  --tls operator-optional \
  --admin-token local-dev \
  --max-requests 16
```

## inspect the shared service contract

```sh
cargo run --quiet --bin ir -- service-report --listen 127.0.0.1:7001
```

## start the service

```sh
cargo run --quiet --bin ir -- \
  --data /tmp/iridium-service-root \
  service-serve \
  --listen 127.0.0.1:7001 \
  --telemetry-endpoint stdout \
  --tls operator-optional \
  --admin-token local-dev \
  --max-requests 16
```

## operator checks

Run these from another terminal while `service-serve` is active:

```sh
curl http://127.0.0.1:7001/livez
curl http://127.0.0.1:7001/readyz
curl http://127.0.0.1:7001/metrics
curl 'http://127.0.0.1:7001/v1/query?q=MATCH+%28n%29+RETURN+n+LIMIT+1'
curl -H 'Authorization: Bearer local-dev' http://127.0.0.1:7001/admin/status
curl -H 'Authorization: Bearer local-dev' 'http://127.0.0.1:7001/admin/lifecycle?action=stop'
```

Expected outcomes:

- `/livez` returns `live`
- `/readyz` returns the service contract JSON
- `/metrics` returns Prometheus-style text metrics
- `/v1/query` returns one row for the seeded node
- `/admin/status` returns the service contract JSON
- `/admin/lifecycle?action=stop` returns a lifecycle response and stops the bounded service loop

## operator artifacts

Generate the product-owned service artifacts after or instead of the manual checks:

```sh
python3 scripts/service_candidate_report.py --report-dir artifacts
python3 scripts/service_lifecycle_report.py --report-dir artifacts
python3 scripts/service_compatibility_report.py --report-dir artifacts
```

This writes:

- `artifacts/service_candidate_report.json`
- `artifacts/service_candidate_report.md`
- `artifacts/service_lifecycle_report.json`
- `artifacts/service_lifecycle_report.md`
- `artifacts/service_compatibility_report.json`
- `artifacts/service_compatibility_report.md`

The compatibility report also refreshes a service-backed retrieval-quality proof on the canonical fixture:

- `artifacts/retrieval_quality_service_report.json`
- `artifacts/retrieval_quality_service_report.md`

## limits

- TLS is config-shaped only. The current service path does not implement encrypted transport.
- Auth is limited to optional bearer-token gating on admin routes.
- The service candidate path is blocking and single-process.
- The current runbook is for evaluator and operator validation, not deployment automation.