feat(graph): introduce graph.inspect.v1 contract and schema for SBOM relationships
Some checks failed
AOC Guard CI / aoc-guard (push) Has been cancelled
AOC Guard CI / aoc-verify (push) Has been cancelled
Concelier Attestation Tests / attestation-tests (push) Has been cancelled
Docs CI / lint-and-preview (push) Has been cancelled
Console CI / console-ci (push) Has been cancelled
Export Center CI / export-ci (push) Has been cancelled

- Added graph.inspect.v1 documentation outlining payload structure and determinism rules.
- Created JSON schema for graph.inspect.v1 to enforce payload validation.
- Defined mapping rules for graph relationships, advisories, and VEX statements.

feat(notifications): establish remediation blueprint for gaps NR1-NR10

- Documented requirements, evidence, and tests for Notifier runtime.
- Specified deliverables and next steps for addressing identified gaps.

docs(notifications): organize operations and schemas documentation

- Created README files for operations, schemas, and security notes to clarify deliverables and policies.

feat(advisory): implement PostgreSQL caching for Link-Not-Merge linksets

- Created database schema for advisory linkset cache.
- Developed repository for managing advisory linkset cache operations.
- Added tests to ensure correct functionality of the AdvisoryLinksetCacheRepository.
This commit is contained in:
StellaOps Bot
2025-12-04 09:36:59 +02:00
parent 4dc7cf834a
commit 600f3a7a3c
37 changed files with 1326 additions and 272 deletions

View File

@@ -0,0 +1,49 @@
# 30-Nov-2025 - UI Micro-Interactions for StellaOps
## Purpose
Define canonical micro-interaction rules (MI1-MI10) for the StellaOps Console so motion, latency, error, and offline behaviors stay accessible, deterministic, and offline-ready. This advisory is the source of truth for UI sprints 0209/0210/0211 and Storybook/Playwright harnesses.
## Scope
- Applies to Angular workspace `src/UI/StellaOps.UI` (Console), shared UI tokens, Storybook stories, and Playwright/axe/perf checks.
- Covers micro-copy/localisation, telemetry events, reduced-motion behavior, and deterministic seeds/snapshots.
## Principles
- Prefer informative micro-interactions over decorative motion; default to reduced-motion safe values.
- Deterministic by default: fixed seeds, frozen fixtures, stable ordering, UTC timestamps.
- Offline-first: no CDN assets; latency/error/offline states always represented with cached assets and copy.
- WCAG 2.1 AA (focus order, keyboard, contrast, reduced motion, status messaging).
## MI Tracks (acceptance)
| ID | Requirement | Acceptance Signals |
| --- | --- | --- |
| MI1 | Motion tokens catalogue (durations 80/140/200/260/320ms; easings `standard`,`decel`,`accel`,`emphasized`; distance scales XS-XL) in `tokens/motion.ts` and SCSS variables. | Storybook token page renders tokens; tokens consumed by at least 3 components (button, modal, banner). |
| MI2 | Reduced-motion rules: prefers-reduced-motion -> durations clamp to 0-80ms, disable parallax/auto-animations; focus/hover states remain visible. | Playwright + axe snapshots with reduced-motion emulate; no animated GIF/Lottie autoplay; acceptance screenshots stable. |
| MI3 | Latency/idle/load patterns: skeletons (<=400ms show), progress (400-1200ms), optimistic states, and offline banners with retry/backoff copy. | Fixtures for slow/failed/offline in Storybook; Playwright asserts state transitions and retry button wiring. |
| MI4 | Error/cancel/undo: deterministic snackbar/toast pattern with keyboard focus, `aria-live=polite`, and 8s undo window. | Playwright e2e shows undo restores prior state; axe passes; snapshot stable. |
| MI5 | Perf budgets: interaction response <=100ms, animation frame budget 16ms avg/50ms p95; LCP placeholder shown; no layout shift >0.05. | Lighthouse CI (offline config) JSON attached; flamechart samples stored under `tests/perf/micro/`. |
| MI6 | Component mapping: table of components -> interaction type -> token usage; avoid bespoke easing outside catalog. | Mapping lives in `docs/modules/ui/micro-interactions-map.md`; lint rule blocks non-catalog easings. |
| MI7 | Telemetry schema: `ui.micro.*` events with versioned schema, fields (tenant, surface, component, action, latency_ms, outcome, reduced_motion, offline_mode, error_code); PII-free. | JSON schema under `docs/modules/ui/telemetry/ui-micro.schema.json`; unit test validates sample payloads. |
| MI8 | Deterministic seeds/snapshots: RNG seeds fixed per story/test; timestamps frozen; CSS animations paused in snapshots. | Storybook stories set `parameters.chromatic.disableAnimation`; Playwright uses `useFakeTimers` + fixed seeds exported from `micro-fixtures.ts`. |
| MI9 | Micro-copy localisation: keys and ICU messages for micro-interaction copy; defaults EN, fallbacks present; no hard-coded strings in components. | i18n extraction shows zero TODO keys; snapshot verifies translated skeleton/error/undo copy. |
| MI10 | Theme/contrast guidance: light/dark/HC tokens for backgrounds, borders, focus rings, and status colors; contrast >= 4.5:1 text, 3:1 UI elements. | Theming doc `docs/modules/ui/micro-theme.md`; axe-color passes for sample stories; focus ring visible in HC mode. |
## Deliverables
- Token catalog: `src/UI/StellaOps.UI/src/styles/tokens/motion.{ts,scss}` with reduced-motion overrides.
- Storybook stories: `apps/storybook/src/stories/micro/*` covering slow, error, offline, reduced-motion, undo flows; deterministic seeds.
- Playwright suite: `tests/e2e/micro-interactions.spec.ts` covering MI2/MI3/MI4/MI8.
- Telemetry schema + validators: `docs/modules/ui/telemetry/ui-micro.schema.json` plus unit test in `src/app/telemetry/__tests__/ui-micro.schema.spec.ts`.
- Mapping doc: `docs/modules/ui/micro-interactions-map.md` linking components to token usage.
## Test & Determinism Rules
- Freeze timers to 2025-12-04T12:00:00Z in stories/e2e; seed RNG with `0x5EED2025` unless scenario-specific.
- All fixtures and snapshots stored under `tests/fixtures/micro/`; no network calls; offline assets bundled.
- Playwright runs with `--disable-animations` and reduced-motion emulation variant.
## Risks & Mitigations
- Workspace absence blocks implementation -> tracked in sprint action #7.
- Token drift across sprints -> add lint rule and CI check for non-catalog easings.
- Localisation regressions -> include i18n extraction in PR CI for micro stories.
## Traceability
- Sprint: `docs/implplan/SPRINT_0209_0001_0001_ui_i.md` (task UI-MICRO-GAPS-0209-011).
- Findings reference: `docs/product-advisories/31-Nov-2025 FINDINGS.md` (MI1-MI10 gap family).

View File

@@ -80,9 +80,22 @@ This advisory consolidates late-November gap findings across Scanner, SBOM/VEX s
9. **MS9 — Metrics/alerts**: Mirror policy `metrics` marks build/import/verify signals required for observability.
10. **MS10 — SemVer/change log**: `changelog` block declares current format version; future bumps must be appended with deterministic notes.
## NR (Notify Runtime) Gaps — NR1NR10
1. **NR1 — Signed, versioned schema catalog**: Publish JSON Schemas for event envelopes, rules, templates, channels, receipts, and webhooks with explicit `schema_version` and `tenant` fields; ship a DSSE-signed catalog (`docs/notifications/schemas/notify-schemas-catalog.json` + `.dsse.json`) and canonical hash recipe (BLAKE3-256 over normalized JSON). Evidence: catalog + DSSE, `inputs.lock` with schema digests.
2. **NR2 — Tenant scoping & approvals**: Require tenant ID on all Notify APIs, channels, and ack receipts; enforce per-tenant RBAC/approvals for high-impact rules (escalations, PII, cross-tenant fan-out); document rejection reasons. Evidence: RBAC/approval matrix + conformance tests.
3. **NR3 — Deterministic rendering & localization**: Rendering must be deterministic across locales/time zones: stable merge-field ordering, UTC ISO-8601 timestamps with fixed format, locale whitelist, deterministic preview output hashed in ledger; golden fixtures for each channel/template. Evidence: rendering fixture set + hash expectations.
4. **NR4 — Quotas, backpressure, DLQ**: Per-tenant/channel quotas, burst budgets, and backpressure rules applied before enqueue; DLQ schema with redrive semantics and idempotent keys; require metrics/alerts for queue depth and DLQ growth. Evidence: quota policy doc + DLQ schema + redrive test harness.
5. **NR5 — Retry & idempotency policy**: Canonical `delivery_id` (UUIDv7) + dedupe key per event×rule×channel; exponential backoff with jitter + max attempts; connectors must be idempotent; ensure out-of-order acks are ignored. Evidence: retry matrix + idempotency conformance tests.
6. **NR6 — Webhook/ack security**: Mandatory HMAC with rotated secrets or mTLS/DPoP for webhooks; signed ack URLs/tokens with nonce, expiry, audience, and single-use guarantees; restrict allowed domains/paths per tenant. Evidence: security policy + negative-path tests.
7. **NR7 — Redaction & PII limits**: Classify template fields, require redaction of secrets/PII in stored payloads/logs, hash-sensitive values, and enforce size/field allowlists; previews/logs must default to redacted variants. Evidence: redaction catalog + fixtures demonstrating sanitized storage and previews.
8. **NR8 — Observability SLO alerts**: Define SLOs for delivery latency, success rate, backlog, DLQ age; standard metrics (`notify_delivery_success_total`, `notify_backlog_depth`, etc.) with alert thresholds and runbooks; traces carry tenant/rule/channel IDs with sampling rules. Evidence: dashboard JSON + alert rules + trace exemplar IDs.
9. **NR9 — Offline notify-kit with DSSE**: Produce offline kit containing schemas, rules/templates, connector configs, verify script, and DSSE-signed manifest; include hash list and time-anchor hook; support deterministic packaging flags and tenant/env scoping. Evidence: kit manifest + DSSE + `verify_notify_kit.sh` script.
10. **NR10 — Mandatory simulations & evidence**: Rules/templates must pass simulation/dry-run against frozen fixtures before activation; store DSSE-signed simulation results and attach evidence to change approvals; require regression tests for each high-impact rule change. Evidence: simulation report + DSSE + golden fixtures and TRX/NDJSON outputs.
## Pending Families (to be expanded)
The following gap families were referenced in November indices and still need detailed findings written out:
- CV1CV10 (CVSS v4 receipts), CVM1CVM10 (momentum), FC1FC10 (SCA fixture gaps), OB1OB10 (onboarding), IG1IG10 (implementor guidance), RR1RR10 (Rekor receipts), SK1SK10 (standups), MI1MI10 (UI micro-interactions), PVX1PVX10 (Proof-linked VEX UI), TTE1TTE10 (Time-to-Evidence), AR-EP1…AR-VB1 (archived advisories revival), BP1BP10 (SBOM→VEX proof pipeline), UT1UT10 (unknown heuristics), CE1CE10 (evidence patterns), ET1ET10 (ecosystem fixtures), RB1RB10 (reachability fixtures), G1G12 / RD1RD10 (reachability benchmark/dataset), UN1UN10 (unknowns registry), U1U10 (decay), EX1EX10 (explainability), VEX1VEX10 (VEX claims), BR1BR10 (binary reachability), VT1VT10 (triage), PL1PL10 (plugin arch), EB1EB10 (evidence baseline), EC1EC10 (export center), AT1AT10 (automation), OK1OK10 / RK1RK10 / MS1MS10 (offline/mirror/Rekor kits), TP1TP10 (task packs), AU1AU10 (auth), CL1CL10 (CLI), OR1OR10 (orchestrator), ZR1ZR10 (Zastava), NR1NR10 (Notify), GA1GA10 (graph analytics), TO1TO10 (telemetry), PS1PS10 (policy), FL1FL10 (ledger), CI1CI10 (Concelier ingest).
- CV1CV10 (CVSS v4 receipts), CVM1CVM10 (momentum), FC1FC10 (SCA fixture gaps), OB1OB10 (onboarding), IG1IG10 (implementor guidance), RR1RR10 (Rekor receipts), SK1SK10 (standups), MI1MI10 (UI micro-interactions), PVX1PVX10 (Proof-linked VEX UI), TTE1TTE10 (Time-to-Evidence), AR-EP1…AR-VB1 (archived advisories revival), BP1BP10 (SBOM→VEX proof pipeline), UT1UT10 (unknown heuristics), CE1CE10 (evidence patterns), ET1ET10 (ecosystem fixtures), RB1RB10 (reachability fixtures), G1G12 / RD1RD10 (reachability benchmark/dataset), UN1UN10 (unknowns registry), U1U10 (decay), EX1EX10 (explainability), VEX1VEX10 (VEX claims), BR1BR10 (binary reachability), VT1VT10 (triage), PL1PL10 (plugin arch), EB1EB10 (evidence baseline), EC1EC10 (export center), AT1AT10 (automation), OK1OK10 / RK1RK10 / MS1MS10 (offline/mirror/Rekor kits), TP1TP10 (task packs), AU1AU10 (auth), CL1CL10 (CLI), OR1OR10 (orchestrator), ZR1ZR10 (Zastava), GA1GA10 (graph analytics), TO1TO10 (telemetry), PS1PS10 (policy), FL1FL10 (ledger), CI1CI10 (Concelier ingest).
Each pending family should be expanded in this document (or split into dedicated, linked supplements) with numbered findings, recommended evidence, and deterministic test/fixture expectations.

View File

@@ -415,7 +415,7 @@ These are the authoritative advisories to reference for implementation:
- SPRINT_0172_0001_0003_notify_ack_tokens.md
- **Related Docs:**
- `docs/modules/notify/architecture.md` - Module architecture
- **Gaps:** `31-Nov-2025 FINDINGS.md` (NR1NR10 remediation task NOTIFY-GAPS-171-014)
- **Gaps:** `31-Nov-2025 FINDINGS.md` (NR1NR10 remediation task NOTIFY-GAPS-171-014; blueprint `docs/notifications/gaps-nr1-nr10.md`)
- **Status:** Fills MEDIUM-priority gap - covers rules engine, channels, noise control, ack tokens
### Graph Analytics & Dependency Insights