Skip to main content

Canonical Implementation Spec

Glass Box Portal Architecture (v2.1)​

Target: Engineering Team Phase: 5 — Client Transparency & Defensibility Status: IN PROGRESS (backend implemented, frontend pending)

1. Core Concept — The “Truth Projector”​

The Glass Box is a read-only, RLS-enforced projection of the Execution Ledger. It allows external parties (clients, auditors, site managers) to view trusted execution truth in situ, without login friction and without distortion.

The Glass Box is NOT​

  • A dashboard (no management or control)
  • A report (no static export)
  • A collaboration tool (no comments, no edits)

The Glass Box IS​

  • Forensic — renders the ledger exactly as recorded
  • Live — reflects execution events as they occur
  • Scoped — access is bounded to a single, explicit principal and scope

The Glass Box does not summarise truth. It projects it.

2. Security & Access — Link Principals​

All Glass Box access is mediated through Link Principals (Tier-1 identity).

2.1 Auth Model Alignment (Critical)​

Link Principals are not user sessions.

  • They do not mint long-lived cookies
  • They do not participate in the ASVS-L3 session lifecycle
  • They are validated per-request and scoped to a single resource

This keeps Link Principals cleanly separated from the cookie-based web auth model defined in ADR-0012.

A Link Principal Token (opaque or strictly scoped JWT) contains:

  • tenant_id
  • org_unit_id
  • principal_type: 'LINK'
  • scope_type: 'ENGAGEMENT' | 'ASSIGNMENT' | 'SUBMISSION' | 'PROGRAMME'
  • scope_id: UUID

Link Principal tokens are short-lived and revocable.

2.3 Enforcement Model (Non-Negotiable)​

All Glass Box queries MUST enforce scope at the SQL level.

RLS alone is insufficient.

Every Glass Box query MUST include an explicit constraint:

WHERE <scope_column> = $scope_id

Examples:

  • Submission Glass Box → submission_id = $scope_id
  • Assignment Glass Box → assignment_id = $scope_id
  • Engagement Glass Box → engagement_id = $scope_id

Invariant: A link principal cannot enumerate resources within the same org. Scope is singular and absolute.

2.4 Hard Invariant — Routing-Level Read-Only​

Glass Box routes MUST reject all non-GET methods (POST, PUT, PATCH, DELETE) at the routing layer.

No mutation logic may exist in these handlers, even accidentally.

3. Data Access strategy — Forensic Integrity​

3.1 Hard Invariant — No Reporting Tables​

The Glass Box MUST query ledger + snapshot sources only. reporting_* tables, materialised views, and authoring tables are explicitly forbidden.

Performance optimisations must never compromise provenance.

3.2 Canonical Data Sources​

Important correction: There is no evidence_events table.

Evidence is represented as typed ledger events within ledger_events.

Filtering is done by event_type.

4. The Four Glass Box Lenses​

Lens 1 — Engagement Glass Box (Golden Thread)​

Question answered:

Is the job or contract on track?

Allowed sources:

  • engagements
  • submissions
  • ledger_events

View:

  • Chronological execution timeline
  • Task completion progress
  • Submission / approval / void events

Optional (Policy-Driven):

  • Milestone ratification via step-up auth (recorded as ledger event)

Lens 2 — Assignment Glass Box (Cohort View)​

Question answered:

Did everyone who was assigned complete the task?

Allowed sources (explicit):

  • assignments
  • users, groups, group_members (for assignment cohort membership)
  • submissions
  • ledger_events

Explicitly forbidden:

  • reporting_*
  • authoring tables
  • pre-aggregated analytics

View:

  • Cohort snapshot (current membership)

  • Status heatmap:

    • 🟢 Completed
    • 🔴 Failed / Flagged
    • ⚪ Pending

  • Aggregate completion counts

This view replaces spreadsheet-based cohort tracking.

Lens 3 — Submission Glass Box (Forensic Truth)​

Question answered:

Is this specific record true?

Allowed sources:

  • submissions
  • submission_items
  • ledger_events (filtered by event_type)

Rendering rules:

  • Frozen Canvas Rendered from submissions.version_snapshot only (never from live authoring tables)

  • Read-Only Answers Overlaid from submission_items

  • Evidence Chain of Custody

    • Derived from ledger_events

    • Filtered by:

      • evidence.metadata.recorded
      • evidence.file.attached
      • evidence.approved
      • evidence.rejected
      • evidence.voided

  • Policy-Aware Verification

    • If policy required L4:

      • Context present → 🟢 Verified (GPS / Device / Time)
      • Context missing → 🔴 Verification Failed

    • If policy < L4:

      • Display Self-Verified / Peer-Verified
      • Never show false failure

  • Amendment History

    • Version toggle
    • Original state remains visible and crossed out
    • Amendments are additive, never destructive

This view proves history preservation, not cleanliness.

Lens 4 — Programme Glass Box (Compliance Passport)​

Canonical naming: Programme (UK spelling, consistent with existing schema)

Question answered:

Is this person qualified to be here right now?

Allowed sources:

  • program_enrolments
  • program_requirements
  • program_progress
  • ledger_events (where relevant)

View:

  • Large status badge: VALID / EXPIRED
  • Requirement checklist
  • Live certificate rendering (non-revocable proof)

5. Implementation Checklist​

Backend (Go)​

  • Implement LinkPrincipalAuth (distinct from user/cookie auth)

  • Enforce GET-only routing for /api/v1/glassbox/**

  • Enforce explicit scope_id constraints in every query (engagement lens already enforces engagement_id)

  • Implement:

    • GetEngagementTimeline
    • GetAssignmentCohortStatus
    • GetSubmissionForensicView
    • GetProgrammePassport

  • CI guard: fail build if Glass Box queries touch reporting_*

Frontend (SvelteKit)​

  • GlassBoxLayout (no navigation, explicit read-only framing)
  • SubmissionReadOnly renderer (snapshot + answers)
  • VerificationBadge (policy-aware, neutral by default)
  • AssignmentHeatmap
  • ProgrammePassport

Security Validation​

  • Cross-scope access returns 403/404 (enforced by scope-id + scope-type checks)
  • Scope enumeration impossible within same org
  • Amendment history renders original + corrected states (submission lens amendmentHistory)
  • L1/L2 submissions never show false verification failures (verification.*Check = not_required)

6. Current Implementation Status (Summary)​

Implemented

  • Engagement Glass Box endpoint (read-only, ledger/submission derived)
  • Engagement timeline + ledger event aggregation
  • Ratification + state hash events (engagement + submission lenses)
  • Link Principal auth flow + Glass Box routes under /api/v1/glassbox/**
  • Assignment / Submission / Programme lenses
  • CI guard against reporting_* usage in Glass Box queries

Outstanding

  • Frontend Glass Box views