Implementation Plan: Workbench Manifest Inspector

Deliver the full Manifest Inspector module for the Workbench UI with tree browsing, JSON/YAML rendering, provenance metadata, and diffing against prior manifest versions. This plan is spec-first and aligns with SDS-054 and PRD-025 (US-025-002).

Traceability

PRD: docs/specs/shared/prd/025-workbench-ui.md (US-025-002, REQ-WB-002)
SDS: docs/specs/shared/sds/054-workbench-ui-service.md (Manifest Inspector Module)
Reference: docs/specs/shared/reference/011-manifest-schema.md (REF-011)

Scope (100% Completion)

Manifest list with searchable metadata and validation status
Manifest tree view with key-path selection and deep-linking
JSON/YAML toggle with syntax highlighting and copy/download
Provenance panel (hash, generation time, SDS/PRD/ADR refs, source SEA-DSL links)
Diff view against prior manifest version (structural + raw)
Robust error handling and empty states
Tests and E2E coverage

Plan

1) Confirm Data Sources and Registry (No Gaps)

Define the canonical manifest inventory location and history storage.
- Primary source: docs/specs/**/<context>.manifest.json and docs/specs/**/*.sds.manifest.json
- History store: artifacts/manifests/<context>/<timestamp>.manifest.json
- Registry index: artifacts/manifests/index.json (latest pointer + history metadata)

Specify the registry index schema for artifacts/manifests/index.json (object keyed by context).

Schema:

{
  "type": "object",
  "additionalProperties": {
    "type": "object",
    "required": ["context", "latest", "history"],
    "properties": {
      "context": { "type": "string" },
      "latest": { "type": "string" },
      "history": {
        "type": "array",
        "items": {
          "type": "object",
          "required": ["manifestId", "timestamp"],
          "properties": {
            "manifestId": { "type": "string" },
            "timestamp": { "type": "string", "format": "date-time" },
            "author": { "type": "string" },
            "message": { "type": "string" },
            "sizeBytes": { "type": "integer", "minimum": 0 },
            "manifestHash": { "type": "string" },
            "tags": { "type": "array", "items": { "type": "string" } },
            "validation": {
              "type": "object",
              "required": ["validationStatus", "validationTimestamp", "validationErrors"],
              "properties": {
                "validationStatus": { "type": "string", "enum": ["valid", "invalid"] },
                "validationTimestamp": { "type": "string", "format": "date-time" },
                "validationErrors": { "type": "array", "items": { "type": "string" } }
              }
            }
          }
        }
      }
    }
  }
}

Semantics: latest points to the most recent manifestId in history; history preserves the immutable chronological record for diff baselines.

Example entry:

{
  "semantic-core": {
    "context": "semantic-core",
    "latest": "semantic-core@2026-01-19T20:01:12Z",
    "history": [
      {
        "manifestId": "semantic-core@2026-01-18T16:45:02Z",
        "timestamp": "2026-01-18T16:45:02Z",
        "author": "sea-ci",
        "message": "regenerate semantic-core",
        "sizeBytes": 184233,
        "manifestHash": "sha256:1a2b3c...",
        "tags": ["ci"],
        "validation": {
          "validationStatus": "valid",
          "validationTimestamp": "2026-01-18T16:45:05Z",
          "validationErrors": []
        }
      }
    ]
  }
}

Extend the pipeline to populate the history store and index.
- Update manifest generation pipeline (e.g., tools/ir_to_manifest.py or a dedicated registry tool) to:
  - Compute manifestHash (sha256)
  - Record generatedAt timestamp (UTC)
  - Capture context, sdsId, prdIds, adrIds
  - Capture sourceSeaPath and sourceSeaHash
  - Update index.json in a deterministic order
Validate manifests server-side using tools/schemas/manifest.schema.json and persist validation status in index.json under validation for each manifest entry (validationStatus, validationTimestamp, validationErrors).

Outcome: A stable manifest registry with historical versions and full provenance for diffing.

2) Backend-for-Frontend (Manifest API)

Align SDS-054 implementation notes with the chosen BFF runtime (FastAPI to match existing service conventions).
Add a Workbench BFF service dedicated to Workbench read endpoints.
- Service: services/workbench-bff/ (FastAPI for parity with existing services)
- Endpoints (SDS-054 aligned):
  - GET /api/manifests → list with metadata, validation status, latest version
  - GET /api/manifests/:id → manifest payload + provenance metadata
  - GET /api/manifests/:id/versions → list of historical versions
  - GET /api/manifests/:id/diff?from=<hash>&to=<hash> → diff payload (JSON Patch)
  - GET /api/manifests/:id/source → source SEA-DSL/ADR/PRD/SDS refs (paths + hashes)

Diff endpoint contract:

Query parameters:
- from (optional): manifest hash (sha256) to diff from. If omitted, defaults to the previous historical entry before to (or previous before latest if to omitted).
- to (optional): manifest hash (sha256) to diff to. If omitted, defaults to latest.

Response format: RFC 6902 JSON Patch array with additional metadata.

{
  "manifestId": "semantic-core",
  "from": "sha256:1a2b3c...",
  "to": "sha256:9f8e7d...",
  "operations": [
    { "op": "replace", "path": "/model/types/Policy", "value": { "fields": ["id", "name"] } },
    { "op": "add", "path": "/runtime/messaging/outbox", "value": { "enabled": true, "table": "outbox_events" } }
  ]
}

Errors:

400 for malformed hash values or inconsistent from/to selection
404 for unknown manifest id or hash not found in registry history

Example error payload:

{ "error": "manifest_hash_not_found", "message": "Hash not found in history", "manifestId": "semantic-core", "hash": "sha256:deadbeef..." }

Example request URLs:
- /api/manifests/semantic-core/diff (defaults to latest vs previous)
- /api/manifests/semantic-core/diff?from=sha256:1a2b3c...&to=sha256:9f8e7d...

Implement storage adapters:
- File-system adapter for registry + history files
- Schema validator adapter (JSON schema)
Enforce read-only and sanitize file access (manifest registry only):
- Normalize and resolve paths, reject any that escape the manifest root (path traversal prevention).
- Allow only .json, .yaml, .yml extensions; reject all others.
- Whitelist directories: docs/specs/ and artifacts/manifests/ only; blacklist everything else.
- Validate manifest structure against tools/schemas/manifest.schema.json before serving.
Add unit tests for registry parsing, diff computation, and validation errors.

Outcome: Production API that provides complete manifest data, provenance, and diff history.

3) Workbench UI: Manifest Inspector Module

Add route and nav item:
- apps/workbench/src/pages/ManifestInspector.tsx (new page)
- apps/workbench/src/App.tsx (route + nav item)
Implement UI components:
- apps/workbench/src/components/ManifestTree.tsx (recursive tree, search, key-path selection)
- apps/workbench/src/components/ManifestProvenance.tsx (hash, timestamps, refs)
- apps/workbench/src/components/ManifestDiffViewer.tsx (structural + raw diff)
- apps/workbench/src/components/ManifestPayloadView.tsx (JSON/YAML toggle with highlight)
Add client API module:
- apps/workbench/src/lib/manifest-api.ts (typed fetch wrapper with error typing)
- apps/workbench/src/types/manifest.ts (manifest DTOs)
UX details:
- Left panel: manifest list with search, filter by context/SDS, validation badge
- Right panel: tree + content view; selection highlights JSON path
- Provenance sidebar: hash, generatedAt, source SEA path, SDS/PRD/ADR IDs
- Diff mode: select “previous version” or explicit baseline
- Empty/error states with clear guidance

Outcome: Fully functional Manifest Inspector with rich inspection and diffing.

4) Developer Experience Enhancements (Low Effort, High Value)

Copy actions:
- Copy manifest hash, JSON path, or SEA-DSL file path to clipboard
- Download manifest as JSON or YAML
Source trace shortcuts:
- Local dev: one-click copies the repo-relative SEA-DSL path to clipboard with visual confirmation; Production: opens the path in the repo web viewer (configured base URL) in a new tab, with clipboard copy as fallback when the viewer is unavailable
- Surface SDS/PRD/ADR refs as quick links to docs
Validation status UI:
- Show schema validation status and surface validation errors inline
- Highlight fields failing schema validation

Outcome: Faster debugging and higher trust in manifest correctness.

5) Verification & QA

Unit tests:
- BFF registry parsing + diff generation
- UI tree selection → JSON path mapping
- JSON/YAML toggle rendering
Integration tests:
- BFF endpoints against sample registry data
- UI fetch → render → diff flow
E2E tests (Playwright):
- Navigate to Manifest Inspector, open manifest, toggle JSON/YAML, inspect provenance
- Diff against previous version and verify structured output

Outcome: Verified end-to-end behavior with no placeholders or stubs.

Definition of Done (P1.4 Complete)

Manifest Inspector is accessible via Workbench nav and route
Manifest list, tree view, provenance, JSON/YAML toggle, and diff are fully functional
API delivers full manifest metadata with schema validation and source tracing
Diffing works against prior versions with selectable baseline
All relevant tests pass; no TODOs or placeholders remain