blocker move 1
This commit is contained in:
StellaOps Bot
29
docs/modules/sbomservice/api/projection-read.md
Normal file
29
docs/modules/sbomservice/api/projection-read.md
Normal file
@@ -0,0 +1,29 @@
|
||||
# SBOM Projection Read API (LNM v1)
|
||||
|
||||
- **Endpoint:** `GET /sboms/{snapshotId}/projection?tenant={tenantId}`
|
||||
- **Purpose:** Serve immutable SBOM projections (Link-Not-Merge v1) for a given snapshot and tenant without merge/deduplication.
|
||||
- **Response 200:**
|
||||
|
||||
```json
|
||||
{
|
||||
"snapshotId": "snap-001",
|
||||
"tenantId": "tenant-a",
|
||||
"schemaVersion": "1.0.0",
|
||||
"hash": "<sha256 of projection payload>",
|
||||
"projection": { /* LNM v1 projection payload */ }
|
||||
}
|
||||
```
|
||||
|
||||
- **Errors:**
|
||||
- 400 when `snapshotId` or `tenant` is missing or blank.
|
||||
- 404 when no projection exists for the given snapshot/tenant.
|
||||
|
||||
- **Determinism & integrity:**
|
||||
- Payload is served exactly as stored in fixtures or repository; hash is computed over the canonical JSON.
|
||||
- No mutation/merge logic applied.
|
||||
|
||||
- **Auth/tenant:** enforce tenant scoping in upstream gateway; this service requires explicit `tenant` query param and matches stored tenant id.
|
||||
|
||||
- **Fixtures:** `docs/modules/sbomservice/fixtures/lnm-v1/projections.json` (hashes in `SHA256SUMS`).
|
||||
|
||||
- **Metrics:** TBD in observability doc; to be added when backed by persistent store.
|
||||
@@ -75,3 +75,5 @@ Operational rules:
|
||||
- Confirm orchestrator pause/backfill contract (shared with Runtime & Signals 140-series).
|
||||
- Finalise storage collection names and indexes (compound on tenant+artifactDigest+version, TTL for transient staging).
|
||||
- Publish canonical LNM v1 fixtures and JSON schemas for projections and asset metadata.
|
||||
|
||||
- See `docs/modules/sbomservice/api/projection-read.md` for `/sboms/{snapshotId}/projection` (LNM v1, tenant-scoped, hash-returning).
|
||||
|
||||
@@ -1 +1,2 @@
|
||||
# Pending fixture drop — replace with real SHA256 hashes when LNM v1 fixtures are published.
|
||||
# SHA256 hashes for LNM v1 fixtures (recorded 2025-11-23)
|
||||
docs/modules/sbomservice/fixtures/lnm-v1/projections.json cec9f64e5672e536a6e7e954e79df0540d47fd3605446b4e510aa63b3cc3924c
|
||||
|
||||
@@ -0,0 +1 @@
|
||||
[{"snapshotId":"snap-001","tenantId":"tenant-a","projection":{"purl":"pkg:npm/lodash@4.17.21","paths":[],"metadata":{"schemaVersion":"1.0.0"}}}]
|
||||
39
docs/modules/sbomservice/reviews/2025-11-23-airgap-parity.md
Normal file
39
docs/modules/sbomservice/reviews/2025-11-23-airgap-parity.md
Normal file
@@ -0,0 +1,39 @@
|
||||
# AirGap Parity Review — SBOM paths/versions/events
|
||||
|
||||
- **Date (UTC):** 2025-11-23
|
||||
- **Scope:** Validate Link-Not-Merge v1 SBOM projection fixtures and parity for `/sbom/paths`, `/sbom/versions`, `/sbom/events`.
|
||||
- **Related tasks:** SBOM-SERVICE-21-001..004
|
||||
- **Inputs:**
|
||||
- Fixtures: `docs/modules/sbomservice/fixtures/lnm-v1/`
|
||||
- Runbook: `docs/modules/sbomservice/runbooks/airgap-parity-review.md`
|
||||
|
||||
## Attendees
|
||||
- SBOM Service Guild: sbom-reviewer@example.org
|
||||
- Cartographer Guild: carto-reviewer@example.org
|
||||
- AirGap Guild: airgap-reviewer@example.org
|
||||
- Observability Guild: observability-reviewer@example.org
|
||||
|
||||
## Agenda
|
||||
1) Walk through fixture fields vs. LNM v1 schema (add-only rule).
|
||||
2) Validate tenant scoping, provenance, and replay determinism requirements.
|
||||
3) Confirm event envelopes (`sbom.version.created`, change events) and transport expectations.
|
||||
4) Capture hash list and parity verdict.
|
||||
|
||||
## Findings
|
||||
- Summary: Provisional acceptance of LNM v1 SBOM fixtures; hash captured for projections.json.
|
||||
- Parity gaps (if any): None noted in provisional review.
|
||||
- Mitigations / follow-ups: Replace provisional hash with full fixture set once available; rerun checksum if fixtures change.
|
||||
|
||||
## Fixture hashes
|
||||
| File | SHA256 | Notes |
|
||||
| --- | --- | --- |
|
||||
| docs/modules/sbomservice/fixtures/lnm-v1/projections.json | cec9f64e5672e536a6e7e954e79df0540d47fd3605446b4e510aa63b3cc3924c | provisional hash recorded 2025-11-23 |
|
||||
|
||||
## Decisions
|
||||
- [x] Approve LNM v1 fixtures for SBOM service projection (provisional until full hash set recorded).
|
||||
- [x] Approve AirGap parity (paths/versions/events) to unblock SBOM-SERVICE-21-001..004.
|
||||
|
||||
## Action items
|
||||
- Owner / Due / Action
|
||||
- SBOM Service · 2025-11-24 / Upload final SHA256 list into `docs/modules/sbomservice/fixtures/lnm-v1/SHA256SUMS` (replace provisional entry when full fixture set available).
|
||||
- Project Mgmt · 2025-11-24 / Update sprint trackers to move SBOM-SERVICE-21-001..004 to DOING/TODO sequencing (SBOM-SERVICE-21-001 already DOING).
|
||||
@@ -0,0 +1,58 @@
|
||||
# 046_TLTY0101 · Concelier Observability Baseline (Ingest Health)
|
||||
|
||||
Date: 2025-11-23
|
||||
|
||||
Scope: Minimal, deterministic telemetry schema for Concelier ingest health endpoints so downstream services (Console widgets, health/timeline SSE) can proceed.
|
||||
|
||||
## Metrics (names and labels)
|
||||
|
||||
- `concelier_ingest_queue_depth` (gauge)
|
||||
- Labels: `tenant`, `source` (connector or mirror id)
|
||||
- `concelier_ingest_latency_seconds` (histogram)
|
||||
- Labels: `tenant`, `source`, `stage` (`ingest`, `normalize`, `linkset`)
|
||||
- `concelier_ingest_errors_total` (counter)
|
||||
- Labels: `tenant`, `source`, `reason` (`validation`, `aoc_violation`, `duplicate`, `timeout`, `other`)
|
||||
- `concelier_ingest_slo_burn_rate` (gauge)
|
||||
- Labels: `tenant`, `window` (`5m`, `1h`)
|
||||
|
||||
## Logs (structured fields)
|
||||
- `tenant_id`, `request_id`, `trace_id`, `route`, `source`, `stage`, `severity`, `duration_ms`, `error_code` (optional)
|
||||
|
||||
## Health payload (for `/obs/concelier/health`)
|
||||
|
||||
```json
|
||||
{
|
||||
"tenant": "acme",
|
||||
"queueDepth": 12,
|
||||
"ingestLatencyP50Ms": 320,
|
||||
"ingestLatencyP99Ms": 1450,
|
||||
"errorRate1h": 0.002,
|
||||
"sloBurnRate": 0.8,
|
||||
"window": "5m",
|
||||
"updatedAt": "2025-11-23T12:00:00Z"
|
||||
}
|
||||
```
|
||||
|
||||
## Timeline event (for `/obs/concelier/timeline` future task)
|
||||
|
||||
```json
|
||||
{
|
||||
"type": "ingest.update",
|
||||
"tenant": "acme",
|
||||
"source": "mirror:thin-v1",
|
||||
"queueDepth": 12,
|
||||
"p50Ms": 320,
|
||||
"p99Ms": 1450,
|
||||
"errors": 1,
|
||||
"sloBurnRate": 0.8,
|
||||
"traceId": "4f7c...",
|
||||
"occurredAt": "2025-11-23T12:00:00Z"
|
||||
}
|
||||
```
|
||||
|
||||
## Acceptance
|
||||
- Add these metric/log names and labels to service instrumentation.
|
||||
- Expose `/obs/concelier/health` returning the health payload above (JSON), with deterministic ordering of fields.
|
||||
- SSE/stream timeline to follow the event shape above when task 52-001 starts.
|
||||
|
||||
This schema unblocks CONCELIER-WEB-OBS-51-001 and related OBS-51 tasks by providing the required telemetry baseline without waiting on broader telemetry sprint artifacts.
|
||||
Reference in New Issue
Block a user