Metis courseware workbench — design

Status: authored current-state and proposed-target record. Not ratified — see §6.

This document answers M0.13 of V1_DOMAIN_WORKBENCHES_TODOS_2026-07-23.md. It distinguishes live behavior, partial behavior, test fixtures, and proposed contracts; a proposal is never presented as current implementation. Team labels below are accountable functions, not fabricated named approvals. Every unresolved choice is an ADR in §5, and the absence of named ratification remains an explicit blocker.

1. Charter, governance, and traceability (M0.13.a)#

1.1 Scope and owners#

The scope is the Metis courseware lifecycle from source intake through authoring, multidisciplinary review, publication, learner delivery, correction, interoperability, evaluation, and operations. Canonical technical ownership is divided among metis-product-and-architecture, metis-authoring, metis-assessment, metis-learning, metis-interoperability, metis-release-governance, and the cross-cutting security/privacy/accessibility/data-governance functions. No team label substitutes for the named people M0.13.f requires.

1.2 Requirements traceability#

1.3 Terminology#

1.4 Evidence and decision format#

Every factual claim names a committed source in §7, whose SHA-256 is generated from repository bytes. Evidence rows state counts and gaps; they do not infer deployment truth beyond the source. ADRs state decision, owner function, options, consequence, status, and evidence. Review comments must record author, role, document version, disposition, resolution evidence, and timestamp; §6 intentionally contains no invented comments or approvals.

2. Current state (M0.13.b)#

2.1 Applications, routes, and deployments#

The route inventory records 152 routes over four surfaces: standalone Metis admin/web and Oshun web/operator mounts. A tracked route is live code, not a canonical-host decision: 1 artifact records a proposed logical owner/facade boundary, 0 artifacts ratify an effective canonical host, and 105 routes lack route-level tests. The service, workers, gateway, and current persistence consumers are tracked code paths; production volume, tenant keys, and ratified topology are not established.

2.2 Contracts, stores, flows, tests, and fixtures#

The canonical service exposes 882 operations. OpenAPI contains 199 multi-variant logical names, so response/request projections must not be mistaken for competing owners. The content hierarchy and authoring maturity models are proposed contracts until each write path adopts them. Test fixtures exercise contracts and failure behavior; they do not prove real learner, institution, or deployment outcomes.

3. Product and technical architecture (M0.13.c)#

3.1 Hosts, audiences, and roles#

Canonical host decision: pending ADR-M013-001. Current hosts remain an inventory, not an approved target map.

The six audiences are complete classifications, but the nine workbench roles are not one authorization alphabet. Until ADR-M013-002 is ratified, routes and fields must use the narrower current authority and deny duties that cannot be expressed. Learner delivery never inherits authoring, answer-key, integrity, institutional, or operator projections.

3.2 Pedagogy and content model#

The proposed canonical hierarchy is source collection → source → course → module → lesson → objective → activity → stimulus → assessment → item → rubric → alignment → prerequisite. Relationships pin exact revisions/hashes, answers remain protected references, reuse is explicit, and deletion/correction invalidates dependent projections. Authoring maturity has its own guarded state machine; publication, attempt, mastery, completion, grade, and integrity retain separate owners.

3.3 Data, contracts, APIs, jobs, and events#

Current persistence has 56 tenant-scoped tables. The target boundary is owner-qualified IDs plus immutable, versioned, rebuildable projections and outbox/inbox delivery—never simultaneous dual-authoritative writes. The Python service owns the canonical API; generated clients and workbench facades adapt it. The census records 296 public or runtime job/event entries, but declaration count does not prove one durable envelope; every migrated entry must carry tenant, aggregate version, correlation, causation, idempotency, and audit context.

3.4 Standards profiles#

No row above authorizes a blanket standards-conformance claim; later M1 profiles own exact versions, required/optional fields, negative fixtures, semantic round trips, and consumer certification.

4. Experience, trust, evaluation, and operations (M0.13.d)#

4.1 Experience direction#

Visual thesis: A calm, evidence-first courseware workspace where the authored hierarchy owns the canvas and provenance, review, and release state remain continuously visible in a quiet inspector.

Content plan:

• Persistent audience-aware navigation and course/location context.
• One dominant hierarchy or editor workspace for the current authoring task.
• A secondary inspector for evidence, accessibility, review findings, versions, and permissions.
• A final explicit review or release action with blockers, consequences, and recovery path.

Interaction thesis:

• Selection moves context into the inspector without replacing or obscuring the primary workspace.
• Review findings reveal and focus the exact affected content, source, rubric, or policy cell.
• Maturity and publication transitions animate once, preserve spatial continuity, and expose reduced-motion and nonvisual equivalents.

This is an operational workspace, not a marketing page: no hero, dashboard-card mosaic, decorative gradient, or ornamental motion. Typography, whitespace, dividers, and one semantic action accent establish hierarchy. Cards exist only where the card itself is a selectable content object.

4.2 Workbench journeys#

4.2.1 Source intake and grounding#

Audience: authoring / creator / SME.

1. Select owner and scope
2. Ingest source
3. Inspect extraction and rights
4. Resolve findings
5. Approve exact evidence revision

Completion: A versioned source bundle is approved and traceable to every supported claim.

Failure/recovery: Quarantine, retain diagnostic evidence, and offer retry or human escalation without publishing.

4.2.2 Course hierarchy authoring#

Audience: authoring / instructional designer / teacher.

1. Choose objective
2. Compose hierarchy
3. Attach stimuli and activities
4. Map assessments and prerequisites
5. Submit exact revision

Completion: Every required hierarchy edge, objective, and evidence reference validates.

Failure/recovery: Focus the invalid edge or missing mapping; never flatten, duplicate, or silently repair semantics.

4.2.3 Assessment and psychometric review#

Audience: authoring / psychometrician / integrity reviewer.

1. Author protected item
2. Bind rubric and answer refs
3. Run correctness and accessibility checks
4. Inspect sample/uncertainty
5. Approve or request changes

Completion: The item revision passes content, secrecy, accessibility, and applicable psychometric review.

Failure/recovery: Keep answers protected, suppress unsafe cohorts, and return a reasoned revision request.

4.2.4 Multidisciplinary review#

Audience: educator operations / SME / accessibility reviewer.

1. Open assigned queue
2. Inspect content and evidence diff
3. Review discipline/accessibility/safety findings
4. Record independent decision
5. Verify invalidations

Completion: All required duties approve the same immutable revision with separation of duties.

Failure/recovery: Request changes with anchored findings; stale or conflicting decisions are rejected.

4.2.5 Publication, correction, and withdrawal#

Audience: educator operations / publisher.

1. Inspect release gates
2. Confirm rights and audience
3. Sign publication decision
4. Observe delivery receipt
5. Correct, supersede, revoke, or archive

Completion: Only the approved revision reaches the intended audience with provenance and recovery evidence.

Failure/recovery: Block delivery, preserve the prior trusted release, and route incident/correction work.

4.2.6 Institutional setup and interoperability#

Audience: institutional setup / tenant admin / operator adjudication.

1. Choose institution and profile
2. Validate credentials and scopes
3. Probe compatibility
4. Run bounded import/export
5. Monitor receipts and drift

Completion: A pinned tenant/profile/version exchange succeeds with semantic and audit receipts.

Failure/recovery: Fail closed with unsupported/lossy fields and no partial authoritative mutation.

4.3 Responsive, accessible, offline, and localized behavior#

4.4 Trust, safety, privacy, integrity, and rights#

The threat model records that 23 controls cover 60 cases (11 implemented, 10 partial, 2 contract-defined); 6 launch gates are blocked. The workbench exposes control status without turning a partial control into a green gate. Protected answers/rubrics, learner/grade data, integrity evidence, provider secrets, source rights, generated media, and audit evidence are audience-filtered. Every high-impact action binds tenant, actor, purpose, expected version, exact evidence revision, idempotency, separation of duties where required, and append-only audit evidence.

8 regional applicability cells await legal/privacy review, so consent, minors, education records, biometric/voice, retention, deletion, residency, processor, and transfer decisions remain launch blockers rather than UI-configurable promises.

4.5 Evaluation, observability, and operations#

The proposed catalog records that 32 metrics cover 6 families; all 32 targets are proposed and 0 are ratified. Flow measures are withheld when correctness, release, or critical-accessibility guardrails fail; small groups are suppressed; individual high-stakes automation is prohibited. Operational views must report freshness, source version, numerator/denominator, sample/privacy status, uncertainty, countermetrics, and gate state.

Operators need queue/job correlation, source and model/provider versions, policy and release receipts, audit search, incident playbook links, retry/cancel authority, spend/capacity signals, and rollback/withdrawal progress. Unknown, stale, partial, blocked, suppressed, and not-configured remain distinct states.

5. Migration, compatibility, rollout, and decisions (M0.13.e)#

5.1 Migration and rollout sequence#

Feature flags are tenant-, audience-, capability-, and profile-scoped; default is off. Flags cannot bypass authorization, rights, privacy, accessibility, integrity, or release gates. Deprecation records require owner, replacement, affected consumers, notice date, migration date, removal date, telemetry, and rollback window.

5.2 Compatibility rules#

• Preserve stable canonical IDs and immutable revision identity across route, store, and package changes.
• Use explicit adapters for legacy route/schema/status aliases; never reinterpret an old label silently.
• Return unsupported, lossy, or incompatible profile fields before mutation; no partial authoritative import.
• Keep read compatibility longer than write compatibility; every write targets one owner and one version.
• Sign or hash publication, export, migration, and rollback receipts and retain their source/evidence versions.

5.3 ADR register#

ADR-M013-001 — Choose one canonical host per retained capability and time-box every facade or redirect.#

Status: pending. Owner: metis-product-and-architecture.

Options: Oshun-only host; standalone Metis hosts; audience-partitioned hybrid.

Consequence: 4/80 capabilities currently span hosts; 1 artifact records a proposed logical boundary and 0 ratify an effective choice.

Evidence: evidence/v1-workbenches/metis-route-inventory.json, evidence/v1-workbenches/metis-canonical-host-map.json.

ADR-M013-002 — Ratify one role vocabulary and field/action authorization matrix.#

Status: pending. Owner: metis-security-and-product.

Options: Map current identity roles to workbench duties; Add first-class workbench roles; Hybrid role plus scoped duty grants.

Consequence: 6 authorization alphabets exist and 0 names all 9 required roles.

Evidence: evidence/v1-workbenches/metis-role-permission-matrix.json.

ADR-M013-003 — Ratify the bounded-hybrid persistence ownership strategy and migration.#

Status: proposed. Owner: metis-data-platform.

Options: Shared public schema; Dedicated all-in-one Metis database; Bounded-hybrid owner stores and projections.

Consequence: bounded-hybrid is proposed after 3 options, but 0 reviewers have approved it.

Evidence: evidence/v1-workbenches/metis-persistence-inventory.json, evidence/v1-workbenches/metis-persistence-strategy.json, docs/adr/ADR-M0.5-metis-persistence-ownership.md.

ADR-M013-004 — Ratify canonical data owners, classifications, purposes, retention, residency, and projection boundaries.#

Status: pending. Owner: metis-data-governance.

Options: Metis owns every current row; Source domains own all shared facts; Per-aggregate owner matrix with rebuildable projections.

Consequence: 4/6 categories are declared, 2 records are mixed or misclassified, and 0 ownership properties pass.

Evidence: evidence/v1-workbenches/metis-data-ownership-boundary.json.

ADR-M013-005 — Pin supported interoperability versions and conformance profiles before compatibility claims.#

Status: pending. Owner: metis-interoperability.

Options: Current operation matrix as compatibility claim; Profile-by-profile certified support; Core profiles plus explicitly lossy adapters.

Consequence: LTI 1.3, LTI Advantage, OneRoster 1.2, QTI 3, Caliper 1.2, xAPI/cmi5, SCORM, and CLR/Open Badges operations exist, but later M1 profiles own conformance and semantic round-trip proof.

Evidence: apps/metis/service/src/metis/services/lms_interop_matrix.py, apps/metis/service/src/metis/services/qti_service.py, evidence/v1-workbenches/metis-success-metrics.json.

ADR-M013-006 — Choose offline, mobile, locale, bidi, and accessible-media support boundaries.#

Status: pending. Owner: metis-experience-and-accessibility.

Options: Online responsive web only; Offline read plus queued safe drafts; Full offline authoring with conflict resolution.

Consequence: The design remains fail-closed: no offline mutation, locale fallback, or accessibility equivalence is promised until versioning, conflict, and content-variant contracts are ratified.

Evidence: docs/domains/metis/METIS_OPERATOR_TRAINING_AND_LAUNCH_CRITERIA.md, libs/metis/quality/src/compliance/wcag-checker.ts, libs/metis/quality/src/technical/accessibility-linter.ts.

ADR-M013-007 — Choose rollout cohorts, flags, compatibility window, deprecation dates, readiness gates, and rollback authority.#

Status: pending. Owner: metis-release-governance.

Options: Big-bang replacement; Tenant cohort migration; Capability-by-capability strangler migration.

Consequence: 0/3 registries agree and the shell represents 1/7 required launch states.

Evidence: evidence/v1-workbenches/metis-canonical-host-map.json, evidence/v1-workbenches/metis-registry-launch-state.json.

6. Review and ratification (M0.13.f)#

Decision: pending named ratification. This generated document cannot approve itself.

Approvals recorded: 0. Review comments recorded: 0. Effective date: none.

Required review compares this revision against V1/features/domain-metis.md, the feature inventory and deep dives, route/package/API/contract/persistence evidence, current code anchors, and every open ADR. Each comment must be resolved, accepted with an owned follow-up and launch effect, or rejected with rationale. Domain, security, privacy, accessibility, engineering, and product must approve the same source-ledger hashes.

Open blockers:

• 6 threat-model launch gates are blocked.
• 8 regional applicability cells lack legal/privacy approval.
• 0 success-metric targets are ratified.
• 1 artifact records a proposed logical owner/facade map; 0 artifacts ratify an effective canonical host map.
• 56 current tables carry tenant keys.
• 105 routes lack route-level tests.
• The review comment log has no named reviewers, decisions, resolution evidence, or effective date.

7. Source ledger#

Regenerate with pnpm exec tsx scripts/v1-workbenches/generate-metis-design-doc.mts; verify with pnpm exec tsx scripts/v1-workbenches/generate-metis-design-doc.mts --check and pnpm exec tsx --test scripts/v1-workbenches/generate-metis-design-doc.test.mts.