AlgoQuest Qbit Education

Embedded CodeProject.AI node operations

Attribution: Jean-Sebastien Beaulieu · ORCID 0009-0007-2904-0443 · SecuredMe · AlgoQuest

Gateway support acknowledgement. This SecuredMe school tool is gateway-compatible. E2B audit support and Datadog observability are routed through the shared SecuredMe gateway when that lane is configured; this repository does not claim a direct E2B or Datadog runtime dependency by default, and no E2B or Datadog secret is stored in this README.

Maintainer intake during active finishing week. This repository is maintained directly on main by the SecuredMe maintainer. Public issues are open for bug reports, documentation corrections, security-safe observations, and reproducible feedback, but opening an issue does not promise a response or a delivery date. Pull requests are not accepted during the active code-finishing week; use issues only until this notice is replaced.

AlgoQuest Qbit Education is the education runtime for the SecuredMe suite.

• Status: pre-alpha — active public development
• License: Secured Educational License 2.0 (LicenseRef-SEL-2.0)
• AI route governance: official classroom workflows are constrained to Codex/OpenAI and Antigravity/Gemini.
• Hero Books status: pre-alpha proof line, not alpha-ready. The deterministic core, Phase 7 prompt quality gates, browser gate, authenticated Builder broker implementation, generated notebook parity, v2 receipt admission, and privacy boundaries are tested locally. Live Auth0/HTTPS deployment, unpacked-extension acceptance, live Colab return, and school approval remain blockers.

The repo now has:

• A dual-surface runtime (/student, /teacher)
• A contract-first interoperability layer with local storage contracts
• A suite-connect decision surface with 12 app queue support
• A local Learning Lab (6 sections) with keyboard navigation
• MkDocs + accessibility controls + theme controls
• A strict local secret-safety posture (no raw student secrets in records)
• The AlgoQuest Hero Books proof line:
  • six audience profiles and six Hero Book worlds
  • first complete fr-CA Mage adaptation with 40 prompts across five acts
  • one-use prompt consumption per AdventureRun
  • deterministic prompt assignment, replay, digests, local resume, and multi-tab conflict detection
  • preserved v1 contracts plus LearnerProfile.v1, MissionEnvelope.v2, AlgorithmArtifactReceipt.v2, and ColabExecutionReceipt.v2
  • a generated notebook at notebooks/mage-two-horizons-primary-5-6-fr-CA.ipynb and public copy under public/notebooks/
  • a typed page-to-extension bridge that sends the mission and admits the Builder artifact before the Colab receipt
  • canonical digest recomputation, mission/artifact binding, stale mission rejection, and secret/identity rejection
  • Tenebris-style ephemeral observation contracts, disabled by default, with no mastery authority

Current blockers for any alpha claim:

• no deployed Auth0/HTTPS/Postgres broker acceptance yet
• no real unpacked-Chromium and live Colab callback acceptance yet
• no real student, teacher, school, or minor approval
• no final 145-action gate decision

npm install
npm run dev

npm test

npm test maps to:

node scripts/hero-books-phase7-act-structure-test.mjs
node scripts/hero-books-phase7-prompt-quality-test.mjs
node scripts/hero-books-contract-test.mjs
node scripts/mage-first-proof-contract-test.mjs
npm run hero-books:a11y-static
npm run build
npx tsc --noEmit
python -m mkdocs build --strict
npm run hero-books:browser
npm run hero-books:gate

The browser gate starts Vite preview from the repository root and waits for the #hero-books section to hydrate before asserting visible text. Override its default 30 second readiness timeout with:

$env:HERO_BOOKS_BROWSER_TIMEOUT_MS='45000'
npm run hero-books:browser

• App.tsx chooses surface from URL pathname:
  • /teacher => teacher
  • all other paths => student
• Clicking Learning Lab switches into a local module mode.
• Lab section order is fixed:
  1. home
  2. problem-types
  3. build-algo
  4. performance
  5. paradigms
  6. innovation
• While in lab mode, left/right arrows move section-by-section.

Student Surface

• Uses validated fixture/contract input as a baseline:
  • readLatestVadLearningEvent() from educationInterop
• Displays:
  • validated artifact score + threshold
  • next-step hints
  • risk flags and consent status
  • student/install metric rows built from fixtures/events
• Supports explicit learner profile toggle:
  • student_minor
  • student_adult

Teacher Surface

• Uses aggregate planning derived from student payload:
  • no raw learner event is shown
  • redacted aggregate metrics and classroom planning fields only
• Shows suite queue projection from install scope/target state.
• Session role/surface consistency is checked before rendering sensitive panels.

• HomeSection.tsx: onboarding cards and surface navigation shortcuts
• ProblemTypesSection.tsx: MCQ quiz with immediate explanation
• BuildAlgoSection.tsx: drag-and-drop algorithm ordering challenge
• PerformanceSection.tsx: linear search simulation with status and step count
• ParadigmsSection.tsx: greedy path walk, dead-end and completion states
• InnovationSection.tsx: topic selector + generated guidance panel

Hero Books is the new governed adventure path for AlgoQuest. It is designed as an educational "livre dont vous etes le heros" system where prompts are selected from a versioned graph rather than improvised freely.

• AlgoQuest owns mission state, prompt assignment, evidence policy, Qbit boundaries, Tenebris boundaries, and local UI.
• mage-two-horizons.primary-5-6.fr-CA.1 is the first complete adaptation.
• The first Mage adaptation has exactly 40 prompts, max 8 prompts per act, unique titles, unique prompt text, prerequisite depth >= 4, at least 6 evidence kinds, and diversified Builder/Colab/Qbit capabilities.
• Story points, milestones, badges, ASCII scenes, Builder receipts, Colab receipts, and Qbit narration never become mastery authority.
• The app exposes two visible paths: adventure view and study/artifact view, synchronized by mission, version, and digest.
• ASCII output must remain bounded and include a linear equivalent for accessibility.

• EducationSessionRole
• StudentLearningEvent
• GuardianArtifactPointer
• TeacherPlanningEvent
• EducationMetricsEnvelope
• QbitIntervention
• GatewayInstallSequence
• Enums/types for EducationSurface, GatewayRole, and ConsentScope

• buildSession() generates WebAuth-compatible session roles for local rendering.
• buildInstallSequence() builds deterministic install state from role/tool/offer.
• emit...() helpers create typed payloads with contract metadata and raw_secret_stored = false.
• validateGatewayContext() enforces:
  • schema/version checks
  • role/surface match
  • expiration window
  • no obvious secret-like fields in payloads

• Default seed fixture: buildInstallSequence('visual-algorithm', 'student_minor', 'enable_for_suite')
• Queue apps (suiteAppsToConnect): algoquest, visual-algorithm, vot-guardian, algorithm-builder, fnpqnn, gateway, ffed-qlc, quanthor, synthia, scholarium, market-guardian, and tesla-workbench, plus current target context handling.
• Consent mapping:
  • skip_for_now => none
  • enable_for_this_tool => tool
  • enable_for_suite => suite

• Raw learner secrets are not persisted by contract in this repo layer.
• Secret-like field filtering is enforced before state writes:
  • hasSecretLikeField() and explicit forbidden token-like key guards.
• No production-grade claims are made from this repo alone.
• All outputs and planning are local/simulation-oriented unless a human-reviewed deployment adds approved backend integration.
• Builder, Colab, Qbit/Codex/Gemini, CodeProject, Timescale, story points, and telemetry have no pedagogical authority in the Hero Books path.
• Tenebris observations are disabled by default and cannot directly modify mastery.
• Organization projections require aggregation and must not expose teacher-private activity.
• Google Colab is an execution surface only; it is not canonical state.
• The closed Builder WebAuth broker contract is proof of boundary design, not live integration proof.

• Config: mkdocs.yml
• Main docs:
  • docs/index.md
  • docs/architecture.md
  • docs/hero-books-pre-alpha.md
  • docs/hero-books-145-action-audit.md
  • docs/hero-books-traceability-matrix.md
  • docs/accessibility/edge-user-console.md
  • docs/accessibility/neurodivergent-comfort.md

• Theme: docs/javascripts/securedme-theme-toggle.js (securedme:theme:v1)
• Accessibility panel: docs/javascripts/securedme-accessibility.js (securedme:a11y:v2, legacy ...:v1)
• Styles:
  • docs/stylesheets/securedme-education.css
  • docs/stylesheets/securedme-theme-toggle.css
  • docs/stylesheets/securedme-accessibility.css

App.tsx
index.tsx
components/
  education/
    EducationHub.tsx
  sections/
    HomeSection.tsx
    ProblemTypesSection.tsx
    BuildAlgoSection.tsx
    PerformanceSection.tsx
    ParadigmsSection.tsx
    InnovationSection.tsx
  ui/
    Card.tsx
    NavButton.tsx
services/
  qbitCompanion.ts
  educationInterop.ts
  heroBooks.js
scripts/
  hero-books-phase7-act-structure-test.mjs
  hero-books-phase7-prompt-quality-test.mjs
  hero-books-contract-test.mjs
  hero-books-accessibility-static-test.mjs
  hero-books-browser-test.mjs
  hero-books-pre-alpha-gate.mjs
notebooks/
  mage-two-horizons-primary-5-6-fr-CA.ipynb
data/
  educationFixtures.ts
constants.ts
types.ts
docs/
  index.md
  architecture.md
  accessibility/
  javascripts/
  stylesheets/
  overrides/
mkdocs.yml
assets/
  brand-selected/
  final*/
  Favio et app icon final/
  ...

Current branch check (before pushing):

git status -sb
git log --oneline --decorate --graph --max-count=8

Push dry-run (to isolate transport vs commit issues):

git push --dry-run origin main:main

If GitHub rejects with GH001: Large files detected:

1. Verify largest outbound objects in current history before rewriting:

# list objects > 100MB in current branch history
$THRESHOLD = 104857600
git rev-list --objects HEAD | ForEach-Object {
  $parts = $_ -split ' ', 2
  if ($parts.Count -eq 2) {
    $obj = $parts[0]
    $path = $parts[1]
    $size = [int64](git cat-file -s $obj)
    if ($size -gt $THRESHOLD) {
      Write-Output ("{0}`t{1}`t{2}" -f $size, $obj, $path)
    }
  }
}

2. If large assets are expected and still needed, implement LFS in main and re-add cleanly:

• git lfs install
• git lfs track "assets/**/*.mp4" "assets/**/*.pdf" (scope as needed)
• add/update .gitattributes
• remove and re-add tracked large files from the right commit point

3. If large object already exists in existing pushed commits, coordinate a proper history rewrite with maintainer approval.

• The authenticated Builder broker exists and passes local integration tests, but it is not yet deployed and accepted with real Auth0, HTTPS, Postgres, Chromium, and Colab.
• The no-copy/paste return path is implemented; live Colab acceptance is still pending.
• No real student, teacher, school, or minor approval.
• Full 60-capability Builder implementation is still broader than the tested Mage proof.
• No backend-backed telemetry sink.
• npm test remains the current release-quality gate, and it now includes Phase 7 prompt quality tests plus the Hero Books browser gate.

• AGENTS.md
• SCHOOL_TOOL_GOVERNANCE.md
• SECURITY.md
• SAFETY.md