stella-ops.org/git.stella-ops.org
1
0
Fork 0
Code Issues Pull Requests Actions 2 Releases Wiki Activity

chore: remove outdated documentation and prep notes

Browse Source 
- Deleted several draft and prep documents related to benchmarks, authority DPoP & mTLS implementation, Java analyzer observation, link-not-merge determinism tests, replay operations, and crypto provider registry.
- Updated the merge semver playbook to reflect current database schema usage.
- Cleaned up the technical development README to remove references to obsolete documents and streamline guidance for contributors.
This commit is contained in:
StellaOps Bot
2025-12-24 12:47:50 +02:00
parent 02772c7a27
commit 40362de568
20 changed files with 6 additions and 758 deletions
Download Patch File Download Diff File Expand all files Collapse all files

31
docs/benchmarks/graph/bench-graph-21-001-prep.md
View File

@@ -1,31 +0,0 @@
# Bench Prep — PREP-BENCH-GRAPH-21-001 (Graph API/Indexer harness)
Status: **Ready for implementation** (2025-11-20)
Owners: Bench Guild · Graph Platform Guild
Scope: Build deterministic Graph benchmark harness for 50k/100k node fixtures measuring API/Indexer latency, memory, and tile cache hit rates.
## Fixtures
- Use SAMPLES-GRAPH-24-003 (40–50k) and extend to 100k via duplication with new ids; store under `docs/samples/graph/50k.ndjson` and `100k.ndjson` with `.sha256` hashes.
- Node ordering deterministic; timestamps fixed to `2025-01-01T00:00:00Z`.
## Harness plan (project: `src/Bench/StellaOps.Bench.GraphApi`)
- Scenarios (repeat 5x; report median/p95):
1. **Viewport fetch**: `/v1/graph/tiles?bbox=<seed>` — measure server latency + tile count.
2. **Path query**: `/v1/graph/path?from=...&to=...` — latency + hops + cache hits.
3. **Overlay apply**: apply policy overlay to 1k nodes; measure apply time and index rebuild cost.
4. **Cold vs warm cache**: run viewport + path with cache cold then warm; capture hit rate.
- Metrics captured as NDJSON per run: `{ scenario, fixture, pass: cold|warm, medianMs, p95Ms, maxMs, rssMb, managedMb, cacheHitRate }` plus start/end UTC timestamps.
- Determinism: fixed seed (`GRAPH_BENCH_SEED=2025-01-01T00:00:00Z`); single-thread option `--threads 1` for reproducibility; clear caches between cold/warm phases.
## Outputs
- Store under `out/bench/graph/api/{runId}/results.ndjson` with `.sha256`.
- Summary CSV optional derived from NDJSON; no dynamic wall-clock in filenames beyond runId.
## Acceptance criteria
- Harness runs offline against local fixtures; no external calls.
- Median/p95 for each scenario produced for both 50k and 100k fixtures; cache hit rate recorded where applicable.
- Re-running with same seed/fixtures yields identical NDJSON (apart from RSS variance).
## Next steps
- Generate fixtures + hashes; wire CLI entry `dotnet run -- graph-api --fixture docs/samples/graph/50k.ndjson --seed 20250101`.
- Add perf dashboard hook if available; otherwise publish artifacts under `out/bench/graph/api/latest/`.

38
docs/benchmarks/graph/bench-graph-21-002-prep.md
View File

@@ -1,38 +0,0 @@
# Bench Prep — PREP-BENCH-GRAPH-21-002 (UI headless graph benchmarks)
Status: **Ready for implementation** (2025-11-20)
Owners: Bench Guild · UI Guild
Scope: Define the Playwright-based UI benchmark that rides on the graph harness from BENCH-GRAPH-21-001 (50k/100k node fixtures) and produces deterministic latency/FPS metrics.
## Dependencies
- Harness + fixtures from BENCH-GRAPH-21-001 (must expose HTTP endpoints and data seeds for 50k/100k graphs).
- Graph API/Indexer stable query contract (per `docs/modules/graph/architecture.md`).
## Benchmark plan
- Runner: Playwright (Chromium, headless) driven via `src/Bench/StellaOps.Bench.GraphUi`.
- Environment:
- Viewport: 1920x1080, device scale 1.0, throttling disabled; CPU pinned via `--disable-features=CPUThrottling`.
- Fixed session seed `GRAPH_BENCH_SEED=2025-01-01T00:00:00Z` for RNG use in camera jitter.
- Scenarios (each repeated 5x, median + p95 recorded):
1. **Canvas load**: open `/graph/bench?fixture=50k` → measure TTI, first contentful paint, tiles loaded count.
2. **Pan/zoom loop**: pan 500px x 20 iterations + zoom in/out (2x each) → record average FPS and frame jank percentage.
3. **Path query**: submit shortest-path query between two seeded nodes → measure query latency (client + API) and render latency.
4. **Filter drill-down**: apply two filters (severity=high, product=“core”) → measure time to filtered render + memory delta.
- Metrics captured to NDJSON per run:
- `timestampUtc`, `scenario`, `fixture`, `p95_ms`, `median_ms`, `avg_fps`, `jank_pct`, `mem_mb`, `api_latency_ms` (where applicable).
- Determinism:
- All timestamps recorded in UTC ISO-8601; RNG seeded; cache cleared before each scenario; `--disable-features=UseAFH` disabled to avoid adaptive throttling.
## Outputs
- NDJSON benchmark results stored under `out/bench/graph/ui/{runId}.ndjson` with a `.sha256` alongside.
- Summary CSV optional, derived from NDJSON for reporting only.
- CI step publishes artifacts to `out/bench/graph/ui/latest/` with write-once semantics per runId.
## Acceptance criteria
- Playwright suite reproducibly exercises the four scenarios on 50k and 100k fixtures with seeded inputs.
- Metrics include p95 and median for each scenario and fixture size; FPS ≥ 30 on 50k fixture baseline.
- Archive outputs are deterministic for given fixture and seed (excluding wall-clock timestamps in filenames; embed timestamps only in content).
## Next steps
- Wire Playwright harness into `BENCH-GRAPH-21-001` pipeline once fixtures ready.
- Hook results into perf dashboard if available; otherwise store NDJSON + hashes.

30
docs/benchmarks/impact/bench-impact-16-001-prep.md
View File

@@ -1,30 +0,0 @@
# Bench Prep — PREP-BENCH-IMPACT-16-001 (ImpactIndex dataset/replay)
Status: **Ready for execution** (2025-12-11)
Owners: Bench Guild · Scheduler Team
Scope: Provide deterministic dataset + replay plan for ImpactIndex throughput benchmark (resolve 10k productKeys; measure latency/throughput/memory).
## Inputs/dataset
- Snapshot file: `docs/samples/impactindex/products-10k.ndjson` (10,000 productKeys, shuffled once with seed `2025-01-01T00:00:00Z`).
- SHA256: `caa79c83b5a9affc3b9cc4e54a516281ddceff4804ce853fee3b62d7afb7ab69` (`products-10k.ndjson.sha256` included).
- Each line: `{ "productKey": "pkg:<ecosystem>/<name>@<version>", "tenant": "bench" }`.
## Benchmark procedure
- Harness location: `src/Bench/StellaOps.Bench/ImpactIndex/impact_index_bench.py`.
- Warmup: 1k lookups (excluded from metrics) to trigger caches.
- Run: process all 10k productKeys twice (cold, warm). Record per-pass statistics.
- Metrics to capture (per pass):
- `throughput_items_per_sec`, `p95_ms`, `p99_ms`, `max_ms` for lookups.
- `rss_mb`, `managed_mb`, `gc_gen2_count` from .NET counters.
- `cache_hit_rate` if cache present.
- Output format: NDJSON; one object per pass with fields `{ pass: "cold"|"warm", startedAtUtc, durationMs, throughput, p95Ms, p99Ms, maxMs, rssMb, managedMb, gcGen2, cacheHitRate }`.
- Determinism: fixed seed, single-threaded option flag `--threads 1` for reproducibility; timestamps in UTC ISO-8601.
## Acceptance criteria
- Dataset and checksum published; harness reads from local sample path (no network). ?
- Benchmark run produces deterministic NDJSON for given seed and hardware profile; differences limited to ?5%.
- Cold vs warm pass metrics logged; throughput target ? 2k items/sec on reference hardware, p95 ? 25 ms.
## Next steps
- Harness command: `python src/Bench/StellaOps.Bench/ImpactIndex/impact_index_bench.py --input docs/samples/impactindex/products-10k.ndjson --output src/Bench/StellaOps.Bench/ImpactIndex/results/impactindex.ndjson --threads 1 --seed 20250101`.
- Surface metrics to perf dashboard once harness lands; otherwise store under `out/bench/impactindex/` with hashes (`results/impactindex.ndjson.sha256` present).

35
docs/benchmarks/policy/bench-policy-20-002-prep.md
View File

@@ -1,35 +0,0 @@
# Bench Prep — PREP-BENCH-POLICY-20-002 (Policy delta benchmark)
Status: **Ready for execution** (2025-12-11)
Owners: Bench Guild · Policy Guild · Scheduler Guild
Scope: Provide deterministic inputs and harness expectations to measure delta policy evaluation vs full runs.
## Goals
- Compare delta evaluation (incremental changes) against full evaluation over the same dataset.
- Capture throughput, latency (p50/p95/p99), and memory/GC impact under deterministic conditions.
## Dataset
- Baseline snapshot: `docs/samples/policy/policy-delta-baseline.ndjson`
- 5,000 records of `{ "tenant": "bench", "policyId": "pol-<0001..5000>", "package": "bench.pkg.<n>", "version": "1.0.<n>", "decision": "allow|deny", "factors": { ... } }`
- Deterministic ordering; SHA256 `40ca9ee15065a9e16f51a259d3feec778203ab461db2af3bf196f5fcd9f0d590` (`policy-delta-baseline.ndjson.sha256`).
- Delta patch: `docs/samples/policy/policy-delta-changes.ndjson`
- 500 changes mixing updates/inserts/deletes (encoded with `op`: "upsert"|"delete").
- Sorted by `policyId` then `op` for deterministic replay; SHA256 `7f9d7f124830b9fe4d3f232b4cc7e2e728be2ef725e8a66606b9e95682bf6318` (`policy-delta-changes.ndjson.sha256`).
## Harness plan (implemented under `src/Bench/StellaOps.Bench/PolicyDelta/policy_delta_bench.py`)
- Run 1 (Full): load baseline snapshot, evaluate full policy set; record metrics.
- Run 2 (Delta): apply delta patch to in-memory store, run incremental evaluation; record metrics.
- Metrics captured to NDJSON per run:
- `{ run: "full"|"delta", startedAtUtc, durationMs, evaluationsPerSec, p50Ms, p95Ms, p99Ms, rssMb, managedMb, gcGen2 }`
- Determinism:
- Use fixed random seed `2025-01-01` for any shuffling; single-threaded mode flag `--threads 1` when reproducibility needed.
- All timestamps in UTC ISO-8601; output NDJSON sorted by `run`.
## Acceptance criteria
- Baseline + delta sample files and SHA256 hashes present under `docs/samples/policy/`.
- Harness reads only local files, no network dependencies; replays produce consistent NDJSON for given hardware.
- Delta run shows reduced duration vs full run; metrics captured for both p95/p99 and throughput.
## Next steps
- Harness CLI: `python src/Bench/StellaOps.Bench/PolicyDelta/policy_delta_bench.py --baseline docs/samples/policy/policy-delta-baseline.ndjson --delta docs/samples/policy/policy-delta-changes.ndjson --output src/Bench/StellaOps.Bench/PolicyDelta/results/policy-delta.ndjson --threads 1 --seed 20250101`.
- Results hashed at `src/Bench/StellaOps.Bench/PolicyDelta/results/policy-delta.ndjson.sha256`.

31
docs/benchmarks/signals/bench-sig-26-001-prep.md
View File

@@ -1,31 +0,0 @@
# Reachability Scoring Bench Prep — PREP-BENCH-SIG-26-001-REACHABILITY-SCHEMA-FIX
Status: Ready for execution (2025-12-11)
Owners: Bench Guild Aú Signals Guild
Scope: Define inputs/fixtures and schema for reachability scoring benchmarks (10k/50k functions) to unblock BENCH-SIG-26-001.
## Dependencies
- Reachability schema hash captured locally for synthetic fixtures.
- Sample callgraph/runtime traces sized for 10k/50k functions.
## Harness
- Project: `src/Bench/StellaOps.Bench/Signals/reachability_bench.py`.
- Inputs:
- Callgraph: `docs/samples/signals/reachability/callgraph-10k.ndjson` (`callgraph-10k.ndjson.sha256`).
- Runtime traces: `docs/samples/signals/reachability/runtime-10k.ndjson` (`runtime-10k.ndjson.sha256`).
- 50k variants under the same directory (`callgraph-50k.ndjson`, `runtime-50k.ndjson` + `.sha256`).
- Schema: `docs/benchmarks/signals/reachability-schema.json` (sha256 `aaa5c8ab5cc2fe91e50976fafd8c73597387ab9a881af6d5d9818d202beba24e`).
- Metrics: facts/sec, p50/p95/p99 per-node latency, peak RSS, managed MB, GC gen2.
- Output: metrics NDJSON + cache NDJSON with reachability flags for each function (consumed by BENCH-SIG-26-002).
## Acceptance
- Schema hash recorded and referenced. ✅
- Sample fixtures published under `docs/samples/signals/reachability/` for 10k/50k. ✅
- Deterministic harness command documented; outputs written locally with `.sha256` hashes. ✅
## Commands
- 10k: `python src/Bench/StellaOps.Bench/Signals/reachability_bench.py --callgraph docs/samples/signals/reachability/callgraph-10k.ndjson --runtime docs/samples/signals/reachability/runtime-10k.ndjson --output src/Bench/StellaOps.Bench/Signals/results/reachability-metrics-10k.ndjson --cache-output src/Bench/StellaOps.Bench/Signals/results/reachability-cache-10k.ndjson --threads 1 --seed 20250101`
- 50k: swap `10k` for `50k` in the command above (`reachability-*-50k.ndjson`).
## Handoff
Use these fixtures + commands to run BENCH-SIG-26-001. Cache outputs (`reachability-cache-*.ndjson`) feed BENCH-SIG-26-002 for policy evaluation overhead measurements.

31
docs/benchmarks/signals/bench-sig-26-002-prep.md
View File

@@ -1,31 +0,0 @@
# Policy Eval with Reachability Cache Prep — PREP-BENCH-SIG-26-002-BLOCKED-ON-26-001-OUTPU
Status: Ready for execution (2025-12-11)
Owners: Bench Guild Aú Policy Guild
Scope: Measure policy evaluation overhead with reachability cache hot/cold/mixed scenarios using outputs from BENCH-SIG-26-001.
## Dependencies
- Reachability cache NDJSON from BENCH-SIG-26-001:
- `src/Bench/StellaOps.Bench/Signals/results/reachability-cache-10k.ndjson` (`.sha256`).
- 50k variant available for heavier runs (`reachability-cache-50k.ndjson` + `.sha256`).
- Policy baseline dataset: `docs/samples/policy/policy-delta-baseline.ndjson` (+ `.sha256`).
- Policy overlay schema (30-001) — using deterministic synthetic mapping in harness; update when official schema lands.
## Harness
- Project: `src/Bench/StellaOps.Bench/PolicyCache/policy_cache_bench.py`.
- Scenarios: cold cache, warm cache, mixed (70/30 warm/cold).
- Metrics: throughput, p50/p95/p99 added latency per evaluation, RSS/managed MB, GC gen2, cache hit rate.
- Inputs: policy baseline + reachability cache NDJSON.
## Commands
- 10k cache with baseline policies:
`python src/Bench/StellaOps.Bench/PolicyCache/policy_cache_bench.py --policies docs/samples/policy/policy-delta-baseline.ndjson --reachability-cache src/Bench/StellaOps.Bench/Signals/results/reachability-cache-10k.ndjson --output src/Bench/StellaOps.Bench/PolicyCache/results/policy-cache.ndjson --seed 20250101 --threads 1`
- Swap cache path to `reachability-cache-50k.ndjson` to stress the larger dataset.
## Acceptance
- Cache input and policy baseline present with hashes. ✅
- Cold/warm/mixed runs emit NDJSON with sorted keys; cache hit rate captured. ✅
- Outputs hashed locally (`policy-cache.ndjson.sha256`) and ready for perf dashboard ingestion. ✅
## Handoff
Use cache outputs from BENCH-SIG-26-001 to run the above command. Compare added latency between cold vs warm runs; mixed scenario should stay within target thresholds (p95 delta ≤ configured budget).

146
docs/dev/authority-dpop-mtls-plan.md
View File

@@ -1,146 +0,0 @@
# Authority DPoP & mTLS Implementation Plan (2025-10-19)
## Purpose
- Provide the implementation blueprint for AUTH-DPOP-11-001 and AUTH-MTLS-11-002.
- Unify sender-constraint validation across Authority, downstream services, and clients.
- Capture deterministic, testable steps that unblock UI/Signer guilds depending on DPoP/mTLS hardening.
## Scope
- Token endpoint validation, issuance, and storage changes inside `StellaOps.Authority`.
- Shared security primitives consumed by Authority, Scanner, Signer, CLI, and UI.
- Operator-facing configuration, auditing, and observability.
- Out of scope: PoE enforcement (Signer) and CLI/UI client UX; those teams consume the new capabilities.
> **Status update (2025-10-19):** `ValidateDpopProofHandler`, `AuthorityClientCertificateValidator`, and the supporting storage/audit plumbing now live in `src/Authority/StellaOps.Authority`. DPoP proofs populate `cnf.jkt`, mTLS bindings enforce certificate thumbprints via `cnf.x5t#S256`, and token documents persist the sender constraint metadata. In-memory nonce issuance is wired (Redis implementation to follow). Documentation and configuration references were updated (`docs/11_AUTHORITY.md`). Targeted unit/integration tests were added; running the broader test suite is currently blocked by pre-existing `StellaOps.Concelier.Storage.Mongo` build errors.
>
> **Status update (2025-10-20):** Redis-backed nonce configuration is exposed through `security.senderConstraints.dpop.nonce` with sample YAML (`etc/authority.yaml.sample`) and architecture docs refreshed. Operator guide now includes concrete Redis/required audiences snippet; nonce challenge regression remains covered by `ValidateDpopProof_IssuesNonceChallenge_WhenNonceMissing`.
>
> **Status update (2025-10-23):** mTLS enforcement now honours `security.senderConstraints.mtls.enforceForAudiences`, automatically rejecting non-mTLS clients targeting audiences such as `signer`. Certificate bindings validate thumbprint, issuer, subject, serial number, and SAN values, producing deterministic error codes for operators. Introspection responses include `cnf.x5t#S256`, and new unit tests cover audience enforcement, binding mismatches, and bootstrap storage. Docs/sample config updated accordingly.
## Design Summary
- Extract the existing Scanner `DpopProofValidator` stack into a shared `StellaOps.Auth.Security` library used by Authority and resource servers.
- Extend Authority configuration (`authority.yaml`) with strongly-typed `senderConstraints.dpop` and `senderConstraints.mtls` sections (map to sample already shown in architecture doc).
- Require DPoP proofs on `/token` when the registered client policy is `senderConstraint=dpop`; bind issued access tokens via `cnf.jkt`.
- Introduce Authority-managed nonce issuance for “high value” audiences (default: `signer`, `attestor`) with Redis-backed persistence and deterministic auditing.
- Enable OAuth 2.0 mTLS (RFC 8705) by storing certificate bindings per client, requesting client certificates at TLS termination, and stamping `cnf.x5t#S256` into issued tokens plus introspection output.
- Surface structured logs and counters for both DPoP and mTLS flows; provide integration tests that cover success, replay, invalid proof, and certificate mismatch cases.
## AUTH-DPOP-11-001 — Proof Validation & Nonce Handling
**Shared validator**
- Move `DpopProofValidator`, option types, and replay cache interfaces from `StellaOps.Scanner.Core` into a new assembly `StellaOps.Auth.Security`.
- Provide pluggable caches: `InMemoryDpopReplayCache` (existing) and new `RedisDpopReplayCache` (leveraging the Authority Redis connection).
- Ensure the validator exposes the validated `SecurityKey`, `jti`, and `iat` so Authority can construct the `cnf` claim and compute nonce expiry.
**Configuration model**
- Extend `StellaOpsAuthorityOptions.Security` with a `SenderConstraints` property containing:
- `Dpop` (`enabled`, `allowedAlgorithms`, `maxAgeSeconds`, `clockSkewSeconds`, `replayWindowSeconds`, `nonce` settings with `enabled`, `ttlSeconds`, `requiredAudiences`, `maxIssuancePerMinute`).
- `Mtls` (`enabled`, `requireChainValidation`, `clientCaBundle`, `allowedSubjectPatterns`, `allowedSanTypes`).
- Bind from YAML (`authority.security.senderConstraints.*`) while preserving backwards compatibility (defaults keep both disabled).
**Token endpoint pipeline**
- Introduce a scoped OpenIddict handler `ValidateDpopProofHandler` inserted before `ValidateClientCredentialsHandler`.
- Determine the required sender constraint from client metadata:
- Add `AuthorityClientMetadataKeys.SenderConstraint` storing `dpop` or `mtls`.
- Optionally allow per-client overrides for nonce requirement.
- When `dpop` is required:
- Read the `DPoP` header from the ASP.NET request, reject with `invalid_token` + `WWW-Authenticate: DPoP error="invalid_dpop_proof"` if absent.
- Call the shared validator with method/URI. Enforce algorithm allowlist and `iat` window from options.
- Persist the `jkt` thumbprint plus replay cache state in the OpenIddict transaction (`AuthorityOpenIddictConstants.DpopKeyThumbprintProperty`, `DpopIssuedAtProperty`).
- When the requested audience intersects `SenderConstraints.Dpop.Nonce.RequiredAudiences`, require `nonce` in the proof; on first failure respond with HTTP 401, `error="use_dpop_nonce"`, and include `DPoP-Nonce` header (see nonce note below). Cache the rejection reason for audit logging.
**Nonce service**
- Add `IDpopNonceStore` with methods `IssueAsync(audience, clientId, jkt)` and `TryConsumeAsync(nonce, audience, clientId, jkt)`.
- Default implementation `RedisDpopNonceStore` storing SHA-256 hashes of nonces keyed by `audience:clientId:jkt`. TTL comes from `SenderConstraints.Dpop.Nonce.Ttl`.
- Create helper `DpopNonceIssuer` used by `ValidateDpopProofHandler` to issue nonces when missing/expired, enforcing issuance rate limits (per options) and tagging audit/log records.
- On successful validation (nonce supplied and consumed) stamp metadata into the transaction for auditing.
- Update `ClientCredentialsHandlers` to observe nonce enforcement: when a nonce challenge was sent, emit structured audit with `nonce_issued`, `audiences`, and `retry`.
**Token issuance**
- In `HandleClientCredentialsHandler`, if the transaction contains a validated DPoP key:
- Build `cnf.jkt` using thumbprint from validator.
- Include `auth_time`/`dpop_jti` as needed for diagnostics.
- Persist the thumbprint alongside token metadata in Mongo (extend `AuthorityTokenDocument` with `SenderConstraint`, `KeyThumbprint`, `Nonce` fields).
**Auditing & observability**
- Emit new audit events:
- `authority.dpop.proof.validated` (success/failure, clientId, audience, thumbprint, nonce status, jti).
- `authority.dpop.nonce.issued` and `authority.dpop.nonce.consumed`.
- Metrics (Prometheus style):
- `authority_dpop_validations_total{result,reason}`.
- `authority_dpop_nonce_issued_total{audience}` and `authority_dpop_nonce_fails_total{reason}`.
- Structured logs include `authority.sender_constraint=dpop`, `authority.dpop_thumbprint`, `authority.dpop_nonce`.
**Testing**
- Unit tests for the handler pipeline using fake OpenIddict transactions.
- Replay/nonce tests with in-memory and Redis stores.
- Integration tests in `StellaOps.Authority.Tests` covering:
- Valid DPoP proof issuing `cnf.jkt`.
- Missing header → challenge with nonce.
- Replayed `jti` rejected.
- Invalid nonce rejected even after issuance.
- Contract tests to ensure `/.well-known/openid-configuration` advertises `dpop_signing_alg_values_supported` and `dpop_nonce_supported` when enabled.
## AUTH-MTLS-11-002 — Certificate-Bound Tokens
**Configuration model**
- Reuse `SenderConstraints.Mtls` described above; include:
- `enforceForAudiences` list (defaults `signer`, `attestor`, `scheduler`).
- `certificateRotationGraceSeconds` for overlap.
- `allowedClientCertificateAuthorities` absolute paths.
**Kestrel/TLS pipeline**
- Configure Kestrel with `ClientCertificateMode.AllowCertificate` globally and implement middleware that enforces certificate presence only when the resolved client requires mTLS.
- Add `IAuthorityClientCertificateValidator` that validates presented certificate chain, SANs (`dns`, `uri`, optional SPIFFE), and thumbprint matches one of the stored bindings.
- Cache validation results per connection id to avoid rehashing on every request.
**Client registration & storage**
- Extend `AuthorityClientDocument` with `List<AuthorityClientCertificateBinding>` containing:
- `Thumbprint`, `SerialNumber`, `Subject`, `NotBefore`, `NotAfter`, `Sans`, `CreatedAt`, `UpdatedAt`, `Label`.
- Provide admin API mutations (`/admin/clients/{id}/certificates`) for ops tooling (deferred implementation but schema ready).
- Update plugin provisioning store (`StandardClientProvisioningStore`) to map descriptors with certificate bindings and `senderConstraint`.
- Persist binding state in Mongo migrations (index on `{clientId, thumbprint}`).
**Token issuance & introspection**
- Add a transaction property capturing the validated client certificate thumbprint.
- `HandleClientCredentialsHandler`:
- When mTLS required, ensure certificate info present; reject otherwise.
- Stamp `cnf` claim: `principal.SetClaim("cnf", JsonSerializer.Serialize(new { x5t#S256 = thumbprint }))`.
- Store binding metadata in issued token document for audit.
- Update `ValidateAccessTokenHandler` and introspection responses to surface `cnf.x5t#S256`.
- Ensure refresh tokens (if ever enabled) copy the binding data.
**Auditing & observability**
- Audit events:
- `authority.mtls.handshake` (success/failure, clientId, thumbprint, issuer, subject).
- `authority.mtls.binding.missing` when a required client posts without a cert.
- Metrics:
- `authority_mtls_handshakes_total{result}`.
- `authority_mtls_certificate_rotations_total`.
- Logs include `authority.sender_constraint=mtls`, `authority.mtls_thumbprint`, `authority.mtls_subject`.
**Testing**
- Unit tests for certificate validation rules (SAN mismatches, expiry, CA trust).
- Integration tests running Kestrel with test certificates:
- Successful token issuance with bound certificate.
- Request without certificate → `invalid_client`.
- Token introspection reveals `cnf.x5t#S256`.
- Rotation scenario (old + new cert allowed during grace window).
## Implementation Checklist
**DPoP work-stream**
1. Extract shared validator into `StellaOps.Auth.Security`; update Scanner references.
2. Introduce configuration classes and bind from YAML/environment.
3. Implement nonce store (Redis + in-memory), handler integration, and OpenIddict transaction plumbing.
4. Stamp `cnf.jkt`, audit events, and metrics; update Mongo documents and migrations.
5. Extend docs: `docs/modules/authority/architecture.md`, `docs/security/audit-events.md`, `docs/security/rate-limits.md`, CLI/UI references.
**mTLS work-stream**
1. Extend client document/schema and provisioning stores with certificate bindings + sender constraint flag.
2. Configure Kestrel/middleware for optional client certificates and validation service.
3. Update token issuance/introspection to honour certificate bindings and emit `cnf.x5t#S256`.
4. Add auditing/metrics and integration tests (happy path + failure).
5. Refresh operator documentation (`docs/modules/authority/operations/backup-restore.md`, `docs/modules/authority/operations/monitoring.md`, sample `authority.yaml`) to cover certificate lifecycle.
Both streams should conclude with `dotnet test src/Authority/StellaOps.Authority/StellaOps.Authority.sln` and documentation cross-links so dependent guilds can unblock UI/Signer work.

37
docs/dev/java-analyzer-observation-plan.md
View File

@@ -1,37 +0,0 @@
# Java Analyzer Observation Writer Plan
_Status: 2025-10-29_
SCANNER-ANALYZERS-JAVA-21-008 (resolver + AOC writer) is blocked by upstream heuristics that need to settle before we can emit observation JSON. This note itemises the remaining work so the analyzer guild can sequence delivery without re-opening design discussions in every stand-up.
## Prerequisite summary
- **SCANNER-ANALYZERS-JAVA-21-004** (reflection / dynamic loader heuristics) – must emit normalized reflection edges with confidence + call-site metadata. Outstanding items: TCCL coverage for servlet containers and resource-based plugin hints. Owners: Java Analyzer Guild.
- **SCANNER-ANALYZERS-JAVA-21-005** (framework config extraction) – required to surface Spring/Jakarta entrypoints that feed observation entrypoint metadata. Add YAML/property parsing fixtures and document reason codes (`config-spring`, `config-jaxrs`, etc.).
- **SCANNER-ANALYZERS-JAVA-21-006** (JNI/native hints) – optional but highly recommended before observation writer so JNI edges land alongside static ones. Coordinate with native analyzer on reason codes.
- **Advisory core** – ensure AOC writer schema (`JavaObservation.json`) is frozen before we serialise to avoid churn downstream.
## Deliverables for SCANNER-ANALYZERS-JAVA-21-008
1. **Observation projection (`JavaObservationWriter`)**
- Inputs: normalised workspace + analyzer outputs (classpath graph, SPI table, reflection edges, config hints, JNI hints).
- Outputs: deterministic JSON containing entrypoints, components, edges, warnings, provenance. Align with `docs/aoc/java-observation-schema.md` once published.
2. **AOC guard integration**
- Serialize observation documents through `Scanner.Aoc` guard pipeline; add unit tests covering required fields and forbidden derived data.
3. **Fixture updates**
- Expand `fixtures/lang/java/` set to include reflection-heavy app, Spring Boot sample, JNI sample, modular app. Record golden outputs with `UPDATE_JAVA_FIXTURES=1`.
4. **Metrics & logging**
- Emit counters (`scanner.java.observation.edges_total`, etc.) to trace observation completeness during CI runs.
5. **Documentation**
- Update `docs/scanner/java-analyzer.md` with reason code matrix and observation field definitions.
## Action items
| Owner | Task | Due | Notes |
|-------|------|-----|-------|
| Java Analyzer Guild | Land reflection TODOs (TCCL + resource plugin hints) | 2025-11-01 | Required for reliable dynamic edges. |
| Java Analyzer Guild | Finish config extractor for Spring/Jakarta | 2025-11-02 | Use sample apps in `fixtures/lang/java/config-*`. |
| Java Analyzer Guild | Draft observation writer spike PR using new schema | 2025-11-04 | PR can be draft but should include JSON schema + sample. |
| Scanner AOC Owners | Validate observation JSON against AOC guard + schema | 2025-11-05 | Blocker for marking 21-008 as DOING. |
| QA Guild | Prepare regression harness + performance gate (<300 ms per fat jar) | 2025-11-06 | Align with SCANNER-ANALYZERS-JAVA-21-009. |
## Reporting
- Track these checkpoints in the Java analyzer weekly sync; once prerequisites are green, flip SCANNER-ANALYZERS-JAVA-21-008 to **DOING**.
- Store schema and sample output under `docs/scanner/java-observations/` so AOC reviewers have a stable reference.

53
docs/dev/lnm-determinism-tests.md
View File

@@ -1,53 +0,0 @@
# Link-Not-Merge Determinism Test Plan
**Task:** MERGE-LNM-21-003 — replace legacy merge determinism suites with observation/linkset regressions now that `NoMergeEnabled` is defaulted to `true`.
## Objectives
- Validate raw advisory documents remain byte-stable through observation/linkset materialisation.
- Ensure conflicts detected during linkset building surface in telemetry and persisted artifacts without merge-side mutation.
- Keep canonical hash output stable for exports/evidence bundles after repeated runs.
## Test Coverage Outline
1. **Raw → Observation determinism**
- Feed canonical advisory raw fixtures containing mixed casing, duplicate aliases, and provenance metadata.
- Assert repeated runs of `AdvisoryObservationFactory` emit identical observations (structural equality + canonical JSON hash).
- Verify raw linkset payload retains original ordering/whitespace while canonical linkset stays normalised.
- Initial coverage implemented via `AdvisoryObservationFactoryTests.Create_IsDeterministicAcrossRuns` (core tests).
2. **Linkset conflict surfacing**
- Build linksets from conflicting advisory observations (e.g., differing severity or status flags).
- Confirm conflict markers propagate to `AdvisoryLinkset` outputs and associated metrics/log records.
- Capture deterministic ordering of conflict explanations for evidence exports.
- Coverage landed via `AdvisoryObservationFactoryTests.Create_PreservesRawReferencesForConflictAudits` (raw linkset + attribute parity) and `AdvisoryEventLogTests.AppendAsync_SortsConflictStatementIds` (canonical conflict JSON + stable hashes).
3. **Evidence/export parity**
- Re-run observation/linkset pipelines against identical fixtures and assert resulting evidence manifests hash-identically.
- Track monotonic `supersedes` chains and ensure canonical link records include `PRIMARY` schemes.
- `JsonExportSnapshotBuilderTests.WriteAsync_DifferentInputOrderProducesSameDigest` now proves export bundles remain byte-identical regardless of advisory enumeration order; digest sampling extends `ProducesIdenticalBytesAcrossRuns`.
## Mongo2Go/OpenSSL toolchain
Concelier solution tests (and most connector suites) depend on Mongo2Go’s embedded `mongod`, which is linked against OpenSSL 1.1. The repo already ships the required libraries in `tests/native/openssl-1.1/linux-x64/{libcrypto.so.1.1,libssl.so.1.1}`; use them instead of installing global packages so offline runners stay deterministic.
1. Add the shim to your shell before executing any Mongo-backed suite:
```bash
export LD_LIBRARY_PATH="$(git rev-parse --show-toplevel)/tests/native/openssl-1.1/linux-x64:${LD_LIBRARY_PATH:-}"
```
2. For single commands you can prefix the invocation (handy for CI copy/paste):
```bash
LD_LIBRARY_PATH="$(pwd)/tests/native/openssl-1.1/linux-x64" \
dotnet test src/Concelier/StellaOps.Concelier.sln --nologo
```
3. The shim’s provenance and troubleshooting notes live in `tests/native/openssl-1.1/README.md`; reference it when mirroring the toolchain into air-gapped runners.
## Migration Steps
- [x] Retire `StellaOps.Concelier.Merge.Tests` determinism suites once observation/linkset equivalents land.
- [x] Introduce new regression fixtures under `StellaOps.Concelier.Core.Tests` (shared via `StellaOps.Concelier.Testing`).
- [ ] Wire test helpers to Mongo in-memory harness for end-to-end parity runs.
- [ ] Update documentation (`docs/migration/no-merge.md`) with validation checklist once new tests are green.
_Pending_: execute suites on a workstation with the .NET 10 preview SDK; local environment lacks a functioning CLI, so validation runs must happen downstream.

4
docs/dev/merge_semver_playbook.md
View File

@@ -69,7 +69,7 @@ db.advisories.aggregate([
]);
```
Pair this query with the indexes listed in [Normalized Versions Query Guide](mongo_indices.md).
**Note:** The above MongoDB query syntax is for reference only. The current system uses PostgreSQL. See `docs/db/SPECIFICATION.md` for current database schema.
## 5. Recommended indexes
@@ -98,7 +98,7 @@ Follow the operational checklist in `docs/modules/devops/migrations/semver-style
- [ ] Capture merge decisions via `decisionReason`.
- [ ] Confirm integration tests include fixtures with normalized rules and SemVer styles.
For deeper query examples and maintenance tasks, continue with [Normalized Versions Query Guide](mongo_indices.md).
For current database schema and query patterns, see `docs/db/SPECIFICATION.md`.
## 8. Storage projection reference

21
docs/modules/attestor/replay-prep.md
View File

@@ -1,21 +0,0 @@
# Attestor Replay Prep — PREP-ATTEST-REPLAY-187-003 (Draft)
Status: Draft (2025-11-20)
Owners: Attestor Guild
Scope: Capture prerequisites for wiring Attestor/Rekor anchoring to replay manifests once scanner record payloads are available.
## Expected inputs
- Replay record schema v1 (from `docs/modules/evidence-locker/replay-payload-contract.md`).
- Evidence Locker bundle location/pointer for replay artefacts.
## Attestation plan
- DSSE envelope type: `stella.replay.manifest` (draft).
- Payload fields: `{record_id, bundle_sha256, policy_run_id?, timestamp}`; signer: Attestor service key; optional Rekor entry when online.
- Verification endpoint proposal: `POST /attestations/replay/verify` accepting bundle pointer + DSSE; returns chain-of-custody summary.
## Open dependencies
- Final replay record schema and bundle pointer format.
- Authority policy on signer identity and Rekor usage in air-gap.
## Handoff
Use this note to unblock PREP-ATTEST-REPLAY-187-003; update when scanner payloads and Authority decisions land.

30
docs/modules/cli/guides/replay-cli-prep.md
View File

@@ -1,30 +0,0 @@
# CLI Replay Prep — PREP-CLI-REPLAY-187-002 (Draft)
Status: Draft (2025-11-20)
Owners: DevEx/CLI Guild
Scope: Define inputs/outputs and offline behaviour needed for CLI replay commands (`scan --record`, `verify`, `replay`, `diff`).
## Command surface (proposed)
- `stella scan --record <image>` → emits replay record NDJSON to stdout or `--out bundle.ndjson`.
- `stella replay --bundle <bundle.ndjson>` → re-run verification offline; accepts `--policy-bundle` to pin policy version.
- `stella diff --bundle <a> --bundle <b>` → compare findings/signals with deterministic ordering; output NDJSON.
- `stella verify --bundle <bundle.ndjson>` → signature/hash verification of replay bundle.
## Inputs
- Replay record schema v1 from Evidence Locker (see `docs/modules/evidence-locker/replay-payload-contract.md`).
- Policy export bundle contract (see `docs/modules/policy/design/export-console-bundle-contract.md`) for policy pinning.
## Outputs
- Deterministic NDJSON; file names content-addressed (`sha256` of payload).
- Exit codes: 0 success, 2 validation error, 3 signature mismatch.
## Offline/air-gap considerations
- No network fetch; all references resolve to local bundle paths.
- Trust roots loaded from CLI config or `--trust-root` file; DSSE verification optional flag `--no-verify` default false.
## Open decisions
- Exact flag names for trust root and policy bundle; align with CLI UX guidelines.
- Where to persist cache/metadata (if any) in offline mode.
## Handoff
Treat this as the prep artefact for PREP-CLI-REPLAY-187-002. Update once replay record schema is finalized.

16
docs/modules/evidence-locker/crypto-provider-registry-prep.md
View File

@@ -1,16 +0,0 @@
# Evidence Locker Crypto Registry Prep — PREP-EVID-CRYPTO-90-001
Status: **Ready for implementation** (2025-11-20)
Owners: Evidence Locker Guild · Security Guild
Scope: Document ICryptoProviderRegistry expectations for Evidence Locker hashing/signing (manifest digests, DSSE, bundle encryption) including sovereign profiles.
## Requirements
- Registry entries must expose: `ProviderId`, `Algorithms` (signing/hash), `KeyUri`, `IsFips`, `IsPQReady`, `SupportsTimestamping`.
- Evidence Locker must select provider via config `EvidenceLocker:Crypto:ProviderId` with default `stella-default`.
- DSSE signing for bundles uses provider’s signing key; hashing uses provider hash list in order (sha256 first, optional gost for RU profile).
- JWKS/keys: provider responsible for exporting JWKS; Evidence Locker caches JWKS via configured `KeyUri`; cache TTL configurable.
## Acceptance criteria
- Prep doc published here; sprint task marked DONE.
- Provider selection/config rules recorded; hashing/signing responsibilities clarified.

24
docs/modules/evidence-locker/validate-bundle-prep.md
View File

@@ -1,24 +0,0 @@
# Validate Bundle Prep — PREP-VALIDATE-BUNDLE-187-005 (Draft)
Status: Draft (2025-11-20)
Owners: QA Guild · CLI Guild · Docs Guild
Scope: Define validation steps for replay bundles once schemas freeze.
## Validation checklist (proposed)
- Verify archive hash vs manifest `bundle.manifest.json` (`sha256`).
- Verify DSSE signature (if present) against trusted keys.
- Recompute Merkle root of bundle file tree; compare to manifest.
- Schema validation: replay records conform to `replay.record.v1`; policy export bundle conforms to `policy.export.console.v1` when included.
- Determinism: run `stella replay` twice on same bundle and assert identical outputs (hash comparison).
## Fixtures/tests
- Golden bundles live under `tests/EvidenceLocker/Bundles/Golden/` (sealed, portable, replay) with `expected.json` and DSSE envelopes.
- `StellaOps.EvidenceLocker.Tests` includes fixture tests that validate Merkle subject, redaction, and replay digest; keep them green when regenerating bundles.
- CLI validation test: `stella verify --bundle <fixture>` returns exit code 0 and prints `verified: true`.
## Open dependencies
- Final schemas from Evidence Locker and Policy export contracts.
- Trust root list for DSSE verification (Authority decision).
## Handoff
Use this prep doc for PREP-VALIDATE-BUNDLE-187-005; expand with concrete fixtures once schemas are frozen.

22
docs/modules/mirror/prep-56-001-thin-bundle.md
View File

@@ -1,22 +0,0 @@
# Mirror Thin Bundle Prep — PREP-MIRROR-CRT-56-001 (Draft)
Status: Draft (2025-11-20)
Owners: Mirror Guild (Assembler)
Scope: Capture requirements to start thin bundle v1 when upstream Sprint 110.D artefacts land.
## Dependencies
- Sprint 110.D assembler foundation (missing in repo).
- Trust root list and TUF metadata locations from release pipeline.
## Proposed thin bundle v1 shape
- Container: tar.gz deterministic; root manifest `mirror.thin.manifest.json`.
- Fields: `bundle_id`, `schema_version`=`mirror.thin.v1`, `created_at`, `source_registry`, `artifacts[] {digest, media_type, size}`, `trust_roots[]`, optional `attestations[]`.
- Merkle root over files for audit.
## Open decisions
- Exact artifact set included in “thin” scope (SBOM only vs SBOM+metadata).
- Required signatures (DSSE/Sigstore) and signer identities.
- Retention/GC policy for thin bundles.
## Handoff
Use this as the PREP artefact for PREP-MIRROR-CRT-56-001; update when assembler foundation drops so schema can be finalized and aligned with `docs/modules/mirror/thin-bundle-assembler.md`.

118
docs/modules/scanner/design/analyzer-prep-0132.md
View File

@@ -1,118 +0,0 @@
# Scanner Analyzer Prep · Sprint 0132
This note captures the unblockers promised in PREP tasks for Sprint 0132. Each subsection gives the artifact location, assumption set, and the handoff needed by downstream implementation tasks.
## SCANNER-ANALYZERS-LANG-11-003 (runtime fusion)
- **Objective:** Define the runtime evidence ingest contract to merge AssemblyLoad/Resolving/PInvoke signals with static edges from 11-002.
- **Inputs required:**
- Static edge export format from 11-002 (AssemblyRef/ModuleRef/PInvoke with reason codes).
- Event listener tap points: `AssemblyLoadContext.Resolving`, `AssemblyLoad`, `NativeLibrary.SetDllImportResolver`, `DynamicDependency` attributes, and optional ETW provider `Microsoft-Windows-DotNETRuntime` (keyword 0x8, task AssemblyLoad).
- **Runtime evidence envelope (AOC-aligned):**
```json
{
"runtime_observation_id": "uuid",
"assembly_name": "System.Text.Json",
"kind": "assembly-load|p-invoke|dynamic-dependency",
"source": "Resolving|AssemblyLoad|NativeLibrary|ETW",
"details": {
"requested_name": "System.Text.Json",
"resolved_path": "<normalized absolute path>",
"assembly_version": "8.0.0.0",
"culture": "neutral",
"package_purl": "pkg:nuget/system.text.json@8.0.0",
"confidence": 0.72,
"reason_code": "runtime-resolve"
},
"timestamp_utc": "2025-11-20T00:00:00Z"
}
```
- **Merge rules for downstream 11-003 implementation:**
- De-dup edges by (assembly_name, resolved_path, kind).
- Prefer static edge confidence when present; runtime adds `confidence_bonus = +0.1` but never exceeds 1.0.
- Keep provenance: `edge.provenance = { "static": bool, "runtime": bool }`.
- **Publication:** This doc section is the frozen location for the runtime ingest contract; downstream tasks should reference this path.
## SCANNER-ANALYZERS-LANG-11-004 (observation export → writer/SBOM)
- **Objective:** Define the observation payload emitted to Scanner writer and SBOM entrypoint tagging.
- **Export envelope (AOC-compliant):**
```json
{
"entrypoints": [
{
"label": "app",
"rids": ["win-x64","linux-x64"],
"tfms": ["net8.0","net8.0-windows"],
"command": "dotnet ./bin/app.dll",
"sources": ["src/App/Program.cs"],
"rank": 1
}
],
"dependency_edges": [
{
"from": "app",
"to": "pkg:nuget/system.text.json@8.0.0",
"reason_code": "assembly-ref",
"confidence": 0.86,
"provenance": {"static": true, "runtime": false}
}
],
"environment_profiles": {
"tfm": "net8.0",
"rid": "linux-x64",
"host_policy": "portable",
"features": ["singlefile:false","trimmed:false","nativeaot:false"]
}
}
```
- **Writer handoff:**
- Serialize as deterministic JSON (sorted keys) to the Scanner writer contract `writer/observations/lang/dotnet`.
- Attach `sbom_entrypoint_tags` derived from entrypoint labels to feed SBOM Service tagging.
- **Publication:** Payload shape and field meanings fixed here for Sprint 0132 downstream work.
## SCANNER-ANALYZERS-LANG-11-005 (fixtures & benchmarks)
- **Objective:** Provide fixture plan so QA can start without waiting on further design.
- **Fixture matrix:**
- Framework-dependent: `net8.0`, `net9.0-preview` sample apps (console + web minimal API).
- Self-contained: `linux-x64` trimmed vs non-trimmed.
- Single-file: `win-x64` single-file publish, include native hosting bundle.
- NativeAOT: `linux-x64` HelloWorld + P/Invoke stub.
- Multi-RID: RID graph `linux-x64`, `linux-arm64`, `win-x64` with RID fallback expectations.
- **Locations:** place fixtures under `src/Scanner/__Tests/Fixtures/DotNet/11-005/*`; store expected observation JSON in `__Tests/Fixtures/DotNet/11-005/expected/*.json` with sorted keys.
- **Bench envelopes:**
- Target <150 ms p95 per project scan on dev laptop, <25 MB heap delta; capture via BenchmarkDotNet and report to `__Benchmarks/11-005.md`.
- **Determinism:** lock timestamps to `1970-01-01T00:00:00Z` in serialized outputs; stable ordering by (entrypoint label, dependency to PURL, reason_code).
## SCANNER-ANALYZERS-NATIVE-20-002 (ELF declared-dependency writer contract)
- **Objective:** Unblock writer schema so native analyzer can emit DT_NEEDED/DT_RPATH/DT_RUNPATH data.
- **Edge record (per ELF binary):**
```json
{
"image": "libssl.so.3",
"build_id": "cafef00d",
"rpath": ["$ORIGIN/lib","/usr/lib"],
"runpath": ["$ORIGIN","/opt/openssl"],
"needed": [
{"name": "libcrypto.so.3", "slot": 0, "version": "OPENSSL_3.0", "reason_code": "elf-dtneeded"},
{"name": "libpthread.so.0", "slot": 1, "version": null, "reason_code": "elf-dtneeded"}
],
"interpreter": "/lib64/ld-linux-x86-64.so.2",
"origin": "virtual-fs",
"confidence": 0.82
}
```
- **Writer path:** `writer/observations/native/elf-declared-deps` (append-only NDJSON; sorted by image name then slot).
- **Redaction:** no host absolute paths; resolve `$ORIGIN` using virtual image root only.
- **Publication:** schema above is the agreed baseline for downstream tasks; time-boxed to Sprint 0132.
## SCANNER-ANALYZERS-NODE-22-001 (isolated runner / scoped build graph)
- **Objective:** Provide a deterministic way to run Node analyzer tests without fanning out the whole solution.
- **Approach:**
- Add target solution filter: `src/Scanner/StellaOps.Scanner.Analyzers.Lang.Node.slnf` including only Node projects + shared test utilities.
- Introduce `Directory.Build.props` override for `Lang.Node` tests to disable cross-solution restore (`DisableTransitiveProjectReferences=true`).
- Test command for CI + local: `dotnet test src/Scanner/StellaOps.Scanner.Analyzers.Lang.Node.Tests/StellaOps.Scanner.Analyzers.Lang.Node.Tests.csproj /p:DisableTransitiveProjectReferences=true --no-restore --logger:"console;verbosity=minimal"`.
- Cache seeds: copy pnpm/Yarn fixtures into `obj/fixtures-cache` during test init; deterministic zip timestamps set to `1980-01-01`.
- **Publication:** This runbook unblocks execution while broader solution build contention is resolved; downstream tasks should adopt this invocation until Sprint 131 completes.
---
**Owners:** Scanner EPDR Guild (DotNet), SBOM Service Guild, Native Analyzer Guild, Node Analyzer Guild.
**Status:** All PREP artifacts published 2025-11-20.

34
docs/replay/replay-api-draft-2025-11-18.md
View File

@@ -1,34 +0,0 @@
# EvidenceLocker Replay API (draft) — 2025-11-18
Scope: EVID-REPLAY-187-001 baseline API surface using shared orchestrator/advisory evidence schemas.
## Endpoints (prefix `/api/evidencelocker/replay`)
- `POST /records` — ingest replay bundle (DSSE + manifest). Request: multipart or JSON with CAS URIs; Response: `{ recordId, bundleDigest }`.
- `POST /verify` — verify replay bundle signatures/hashes. Request: `{ bundleDigest | bundleUri }`; Response: `{ status: "pass|fail", findings: [] }`.
- `POST /replay` — schedule replay job against stored records. Request: `{ recordId, targetTenant, policyRevisionId? }`; Response: `{ jobId }`.
- `POST /prune` — enforce retention policy. Request: `{ maxAgeDays, keepLatestPerDigest: bool }`; Response: `{ pruned: int }`.
## Models (draft)
```json
{
"recordId": "uuid",
"bundleDigest": "sha256:...",
"bundleUri": "cas://evidence/replay/{digest}",
"tenant": "string",
"ingestedAt": "2025-11-18T12:00:00Z",
"dsse": {
"payloadType": "application/vnd.stellaops.replay+json",
"payload": "base64",
"signatures": [ { "keyid": "...", "sig": "..." } ]
}
}
```
## Retention policy draft
- Default: `maxAgeDays = 30`, `keepLatestPerDigest = true`.
- Deterministic pruning order: sort by `ingestedAt` ascending, then `recordId`.
## Notes
- Align request/response DTOs with `StellaOps.Orchestrator.Schemas` naming (camelCase, UTC ISO-8601).
- CLI verbs `stella evidence replay record|verify|replay` to mirror these routes (see CLI-REPLAY-187-002).
- Update `docs/replay/DETERMINISTIC_REPLAY.md` once finalized.

20
docs/runbooks/replay_ops_prep_187_004.md
View File

@@ -1,20 +0,0 @@
# Replay Ops Runbook Prep — PREP-RUNBOOK-REPLAY-187-004 (Draft)
Status: Draft (2025-11-20)
Owners: Docs Guild · Ops Guild
Scope: Capture required sections for the replay operations runbook once APIs are finalized.
## Runbook sections to include
1) **Prechecks**: confirm trust roots, air-gap status, Evidence Locker availability, and bundle integrity (`sha256`, DSSE verification).
2) **Ingestion**: steps to POST replay records to Evidence Locker (`/replay/records`), expected responses, retry/backoff guidance.
3) **Verification**: CLI commands (`stella verify --bundle`), Attestor verification call once available, interpreting results.
4) **Replay/Compare**: `stella replay` and `stella diff` workflows, deterministic output locations, common failure modes.
5) **Observability**: log/metric names to watch (to be filled after Evidence Locker/CLI finalize telemetry).
6) **Escalation**: contacts for Scanner/CLI/Attestor/Evidence Locker guilds.
## Dependencies
- Replay payload schema (`docs/modules/evidence-locker/replay-payload-contract.md`).
- CLI and Attestor prep docs for command/API details.
## Handoff
When APIs finalize, merge this content into `docs/runbooks/replay_ops.md` and retire this prep stub.

34
docs/samples/linkset/prep-22-001.md
View File

@@ -1,34 +0,0 @@
# Samples Prep — PREP-SAMPLES-LNM-22-001 / 22-002
Status: **Ready for implementation** (2025-11-22)
Owners: Samples Guild · Concelier Guild · Excititor Guild
Scope: Produce finalized advisory linkset samples aligned to frozen Concelier linkset schema (LNM-21-002 freeze on 2025-11-20) and extend the same fixture set with Excititor observation/VEX payloads for phase 22-002.
## Inputs
- Link-Not-Merge schema: `docs/modules/concelier/link-not-merge-schema.md` (frozen 2025-11-20) and samples under `docs/samples/lnm/`.
- Evidence bundle v1 and console fixtures (for hashes) already published.
## Deliverables
- Two NDJSON fixtures placed under `samples/linkset/`:
- `lnm-advisories-sample.ndjson` — 1k advisory observations with conflicts (NVD vs GHSA vs OSV) using frozen schema.
- `lnm-vex-sample.ndjson` — 500 VEX linkset entries with differing exploitability per product.
- Each file accompanied by `.sha256` hash.
- README (`samples/linkset/README.md`) describing schema version, generation seed, and deterministic ordering rules.
## Excititor extension (PREP-SAMPLES-LNM-22-002)
- Extend NDJSON fixtures with Excititor-origin observations:
- `lnm-excititor-vex-sample.ndjson` — 250 Excititor VEX chunks with sealed-mode flags and provenance hashes.
- `lnm-excititor-observations.ndjson` — 250 observation records showing worker/runtime traces.
- Determinism: reuse seed above; order by `observationId`; timestamps fixed to `2025-01-02T00:05:00Z`.
- Additional hashes recorded alongside existing `.sha256` files.
- Document Excititor-specific provenance fields (chunkId, evidenceBundleId, tenantId) in `samples/linkset/README.md`.
## Determinism
- Generation seed: `2025-01-01T00:00:00Z` (use in faker/RNG).
- Sort records by `observationId` before writing; timestamps set to deterministic `2025-01-02T00:00:00Z` for all entries.
## Acceptance criteria
- Files validate against frozen LNM schema without additional fields.
- Hashes recorded; no external network calls to create fixtures.
- README references the schema doc and seed; links added back into Sprint 0509 Delivery Tracker.

9
docs/technical/development/README.md
View File

@@ -13,12 +13,11 @@ Resources for contributors building features, plug-ins, connectors, and tests.
- [../10_PLUGIN_SDK_GUIDE.md](../../10_PLUGIN_SDK_GUIDE.md) – plug-in lifecycle, manifests, packaging.
- [../10_CONCELIER_CLI_QUICKSTART.md](../../10_CONCELIER_CLI_QUICKSTART.md) – local Concelier + CLI workflow for advisory ingestion.
- Developer guides under [../dev/](../../dev/):
- Connector playbooks (`30_EXCITITOR_CONNECTOR_GUIDE.md`, `30_EXCITOR_CONNECTOR_GUIDE.md`, `concelier-connector-research-20251011.md`, `kisa_connector_notes.md`).
- Authority and DPoP guidance (`31_AUTHORITY_PLUGIN_DEVELOPER_GUIDE.md`, `authority-dpop-mtls-plan.md`, `authority-plugin-di-coordination.md`, `authority-rate-limit-tuning-outline.md`, `32_AUTH_CLIENT_GUIDE.md`).
- Analyzer and cache configuration (`SCANNER_CACHE_CONFIGURATION.md`, `java-analyzer-observation-plan.md`, `EXCITITOR_STATEMENT_BACKFILL.md`).
- Normalisation & merge references (`aoc-normalization-removal-notes.md`, `merge_semver_playbook.md`, `normalized-rule-recipes.md`, `normalized_versions_rollout.md`).
- Connector playbooks (`30_EXCITITOR_CONNECTOR_GUIDE.md`, `kisa_connector_notes.md`).
- Authority and DPoP guidance (`31_AUTHORITY_PLUGIN_DEVELOPER_GUIDE.md`, `32_AUTH_CLIENT_GUIDE.md`).
- Analyzer and cache configuration (`SCANNER_CACHE_CONFIGURATION.md`, `EXCITITOR_STATEMENT_BACKFILL.md`).
- Normalisation references (`normalized-rule-recipes.md`).
- Operational templates and fixtures (`templates/`, `fixtures.md`).
- Mongo/Cartographer details (`mongo_indices.md`, `cartographer-graph-handshake.md`).
## CLI, SDKs & Automation
- [../09_API_CLI_REFERENCE.md](../../09_API_CLI_REFERENCE.md) – authoritative CLI commands and flags (use for scripting).