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
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:
@@ -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).
|
||||
@@ -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 — NR1–NR10
|
||||
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:
|
||||
- CV1–CV10 (CVSS v4 receipts), CVM1–CVM10 (momentum), FC1–FC10 (SCA fixture gaps), OB1–OB10 (onboarding), IG1–IG10 (implementor guidance), RR1–RR10 (Rekor receipts), SK1–SK10 (standups), MI1–MI10 (UI micro-interactions), PVX1–PVX10 (Proof-linked VEX UI), TTE1–TTE10 (Time-to-Evidence), AR-EP1…AR-VB1 (archived advisories revival), BP1–BP10 (SBOM→VEX proof pipeline), UT1–UT10 (unknown heuristics), CE1–CE10 (evidence patterns), ET1–ET10 (ecosystem fixtures), RB1–RB10 (reachability fixtures), G1–G12 / RD1–RD10 (reachability benchmark/dataset), UN1–UN10 (unknowns registry), U1–U10 (decay), EX1–EX10 (explainability), VEX1–VEX10 (VEX claims), BR1–BR10 (binary reachability), VT1–VT10 (triage), PL1–PL10 (plugin arch), EB1–EB10 (evidence baseline), EC1–EC10 (export center), AT1–AT10 (automation), OK1–OK10 / RK1–RK10 / MS1–MS10 (offline/mirror/Rekor kits), TP1–TP10 (task packs), AU1–AU10 (auth), CL1–CL10 (CLI), OR1–OR10 (orchestrator), ZR1–ZR10 (Zastava), NR1–NR10 (Notify), GA1–GA10 (graph analytics), TO1–TO10 (telemetry), PS1–PS10 (policy), FL1–FL10 (ledger), CI1–CI10 (Concelier ingest).
|
||||
- CV1–CV10 (CVSS v4 receipts), CVM1–CVM10 (momentum), FC1–FC10 (SCA fixture gaps), OB1–OB10 (onboarding), IG1–IG10 (implementor guidance), RR1–RR10 (Rekor receipts), SK1–SK10 (standups), MI1–MI10 (UI micro-interactions), PVX1–PVX10 (Proof-linked VEX UI), TTE1–TTE10 (Time-to-Evidence), AR-EP1…AR-VB1 (archived advisories revival), BP1–BP10 (SBOM→VEX proof pipeline), UT1–UT10 (unknown heuristics), CE1–CE10 (evidence patterns), ET1–ET10 (ecosystem fixtures), RB1–RB10 (reachability fixtures), G1–G12 / RD1–RD10 (reachability benchmark/dataset), UN1–UN10 (unknowns registry), U1–U10 (decay), EX1–EX10 (explainability), VEX1–VEX10 (VEX claims), BR1–BR10 (binary reachability), VT1–VT10 (triage), PL1–PL10 (plugin arch), EB1–EB10 (evidence baseline), EC1–EC10 (export center), AT1–AT10 (automation), OK1–OK10 / RK1–RK10 / MS1–MS10 (offline/mirror/Rekor kits), TP1–TP10 (task packs), AU1–AU10 (auth), CL1–CL10 (CLI), OR1–OR10 (orchestrator), ZR1–ZR10 (Zastava), GA1–GA10 (graph analytics), TO1–TO10 (telemetry), PS1–PS10 (policy), FL1–FL10 (ledger), CI1–CI10 (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.
|
||||
|
||||
|
||||
@@ -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` (NR1–NR10 remediation task NOTIFY-GAPS-171-014)
|
||||
- **Gaps:** `31-Nov-2025 FINDINGS.md` (NR1–NR10 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
|
||||
|
||||
Reference in New Issue
Block a user