You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
README.md is the front door. This file is the map: where each subsystem physically lives, its
leverage files, and its honest state. Numbers live in ledgers, not prose — cite
docs/current-state.yaml (generated by tools/build_current_state.py, staleness-gated) and the
.meta.json beside each artifact rather than copying a tally here. candidate ≠ certified ≠ deployed and facts ≠ occurrences ≠ entries ≠ appearances are never collapsed. Authority
precedence is docs/INDEX.md §1; python tools/check_regressions.py ending ALL PASS is the only
accepted evidence of a green state.
1. The product in one paragraph
A Qurʾānic occurrence — addressed exactly as quran:S:A:W — is analysed by the ṣarf (morphology),
naḥw (syntax) and tarkeeb (iʿrāb composition) skills; the analysis decomposes into typed facts,
each certified individually against an evidence ladder with a hash-chained event trail; certified
facts become typed graph edges, and one canonical fact artifact per occurrence is transcluded —
projected identically onto every page showing that occurrence, same projection hash everywhere.
Those projections are what the rich colour segmentation and hover glossing of qamus.dawah.wiki
render (the live app this repo feeds and never writes to). Reading the projection back surfaces
defects, which return as fixtures, rules and skill increments, so the next occurrence is analysed
better, not merely later. The curriculum substrate absorbs the same certified state into a learner
ladder and the tutor drills against it. Nothing leaves the loop uncertified: a word the engine cannot
confidently author stays PENDING.
2. The data plane, subsystem by subsystem
2.1 The lexicon — the 2,092 entries
what it is
The complete offline, redistribution-safe export of every current Qamus entry (947 verb / 1,045 noun / 100 particle). Fully portable: the engine reads qamus/data/current/ with no live server access, and the export is regenerable byte-identically from the private store. Public-safe by construction — authorship, moderation, timestamps and any unknown field are stripped at export and logged in the manifest.
tools/query_current_qamus.py; input to every subsystem below
state
Complete and authored; counts at docs/current-state.yaml#entries. Open blocker: the entries.jsonl checksum mismatch (qamus/reports/dataset-integrity-blocker.md, docs/blockers.yaml).
2.2 The example-āyah universe & occurrence identity
what it is
One row per displayed-token appearance across all 2,092 entry pages, plus a rollup at the unique-occurrence grain. This is where quran:S:A:W identity is established: an occurrence is a canonical token address, an appearance is one rendering of it on one page. The two are different denominators and are never merged; pause-mark tokens are excluded from word denominators.
the particle matrix, the corpus projection manifest, every reverse index
state
Built and gated; totals at docs/current-state.yaml#example_ayah_universe. Recall-tier alignment bases (loose, loose_word_unique) are candidate only, never a certification basis — stated in the meta file itself.
2.3 LargeLexicon
what it is
A source-clean, dependency-free candidate/lookup substrate generated from the same 2,092 entries: lemma / form / stem tables plus a sharded all-visible-qword denominator and crosswalk graph. It is a worklist accelerator and an abstention-gated parser candidate source — explicitly not a disambiguator, not live Qamus progress, not certified NLP. "Coverage is not disambiguation": collisions route to quarantine, never to a winner.
data
fusha/lexicon/largelexicon/{lemma-source,form-source}.full.jsonl · fusha/morphology/data/largelexicon-stems.full.jsonl · qamus/indexes/largelexicon/ (qword denominator + crosswalk shards, named by *.manifest.json)
tools/largelexicon_table_reader.py (the only sanctioned denominator access) · tools/fusha_suggest.py · tools/fusha_text_check.py · curriculum/largelexicon-tutor-routing.md
state
Tables are row version @1 audited against stricter @2 schemas — a non-zero validation exit is expected until an owner-authorized regeneration. Crosswalk counts come from the manifest, never prose. As-built audit + open GAPs: docs/subsystems/largelexicon-as-built.md (GAP-L1 harness wiring; GAP-L3 zero eligible typed edges ⇒ zero bridge candidates).
2.4 The particle candidate matrix
what it is
Every candidate particle occurrence over the example-āyah universe, per particle and per P-family, with a list of function candidates per row. It is the discovery surface for particle work: no row is certified, function_candidates is never a winner, and clitic-vs-free is a heuristic classification pending segmentation evidence. Its rows are candidate links — never "particle occurrences".
tools/validate_p007_universe.py (recomputes every tally, never trusts one)
consumer
the certification lanes; the queue heads in qamus/work-queues/next-actions.jsonl
state
Candidate lattice only; queues at p007-reverse-universe.meta.json#state_tallies and docs/current-state.yaml#p007_reverse_universe. Recorded gaps: p001/p008 are affix-shaped and not strict-prefix discoverable; مَا (P099) still carries an undifferentiated homograph candidate list at every occurrence (ma_function_disambiguation_deficit).
2.5 Typed facts + certification
what it is
An occurrence is not certified — its facts are. Each occurrence decomposes into typed rows (clitic_host_segmentation, contextual_function, governor_relation, case_mood_governor, attachment_geometry, …), each with its own evidence mode, guards, defeaters and dependencies; the certifier moves a fact candidate → review_required → certified (or blocked/rejected) against the ladder, writing an append-only hash-chained event trail. Any iʿrāb-bearing conclusion that reaches a learner needs a two-vote artifact — two independent reviewers agreeing on conclusion and governed reason key, never on gloss text. Revocation cascades to dependents mechanically.
data
qamus/examples/p007-li-pilot/typed-facts.jsonl + certification/ (the 12-occurrence flagship) · qamus/certification/p007-geometry-wave/{typed-facts,events}.jsonl (the geometry wave trail)
typed-edge construction · two-surface projection · FUSHA-BENCH gold
state
docs/current-state.yaml#certified_typed_facts deliberately separates in_repo_event_verified (recomputed from committed trails) from reported_not_in_repo (owner-packet lanes not committed here) — never quote one merged number. The geometry wave certifies mechanical geometry only, not identity/function/sense; entry-level certification is still the pilot's P007_ENTRY_LINKS_CERTIFIED. Nothing certified is deployed; the certification authority itself is proposed, not adopted.
2.6 Transclusion
what it is
A solved fact lives once at a canonical address and every page that shows it transcludes it — a projection of a graph, never a copy of text. Nine node types and 31 typed edge types live in one graph (particle edges are appended, not a parallel graph). Three invariants carry the weight: reverse indexing (every entry can list its certified occurrences), appearance parity (every appearance of one occurrence carries the same projection hash, so a cross-page fork is a defect by construction), and reciprocity (forward and reverse views must agree).
docs/architecture/transclusion-graph.md (identity rules + 4 worked examples) · docs/parser/TRANSCLUSION.md
state
Invariants gated in the harness; per-artifact tallies live in each .meta.json (e.g. citation-display-edges.meta.json, candidate_only: true). Entry completion is reported on the named 12-state ladder, never as a bare percentage.
2.7 Meta-transclusive lattice projection
what it is
Operationally this means reviewed METHODS are reused as guarded candidates; conclusions are never copied. A fact certified at quran:S:A:W applies exactly there. Reuse elsewhere is licensed only by a registered projector with named guards and a gate tier, and its output is a candidate that re-enters the pipeline at the lattice stage — never at the projection stage. Surface similarity never authorizes reuse; a homograph surface routes to two-vote instead of auto-projecting.
tools/validate_meta_transclusion_projection.py --require-exact-rows (the ANDON false-closure guard) · tools/validate_segment_completeness.py
doc
docs/architecture/meta-transclusive-projection.md — the 15 stages, §3 the five reuse postures and their greppable encodings, §4 false closure
state
Candidate-only — nothing currently registered is auto_safe. The corpus-scale consumers (tools/build_corpus_projection_manifest.py, tools/build_corpus_fact_projection_batch.py) report colour and hover as not_available for every word row rather than claiming a rich projection; the geometry batch's own boundary is partial_certified_geometry_only, zero website payloads, zero live outputs (docs/subsystems/qamus-corpus-projection-map.md).
2.8 The ṣarf & naḥw skills
what it is
Decision procedures, not a model. Ṣarf decides word form (root, POS, wazn, clitics, homograph quarantine) before a gloss is authored; naḥw decides how sentence context changes it (particle function, governor/iʿrāb, referent, negation scope). The grammar-safety ANDON governs both: a correct answer with wrong iʿrāb reasoning is unsafe, so two independent checks must agree on conclusion and reasoning. Released tier is @2; increments @2.1–@2.4 are CANDIDATE and do not amend it.
Read docs/subsystems/sarf-executable-map.md and nahw-executable-map.md for coverage — both are file:line-cited and both insist eval rows ≠ behaviourally decided rows: a bank counts as implemented_and_consumed only when a named production consumer decides each row, and every uncovered property is packetized rather than rounded up.
2.9 The curriculum substrate
what it is
The inherited six-level (A1–C2) curriculum absorbed clean-room: committed artifacts carry hashes, counts, titles/slugs and independently authored derived structures only — no lesson prose, exercises or answer keys, and the source site is never named. Absorbed lessons consolidate into canonical instructional units (prerequisites, recognition criteria, learner errors, rival analyses), then cut into tranches. Curriculum prose is not linguistic authority: every proposition carries a qualification status and this subtree contains zero certified rows.
tools/validate_curriculum_l1l6.py (--self-test) · CI .github/workflows/curriculum-l1l6-gate.yml (every generated plane recomputed live — stale artifacts are red)
consumer
tools/curriculum_unit_consumer.py (NON-AUTHORITATIVE fixture harness) · tools/curriculum_flywheel_runner.py (development evidence only — not the canonical linguistic flywheel)
state
The milestone is 234 = 226 inherited + 8 GPS supplement, tracked with separate denominators (AGENTS.md §Public issue board). Absorption, canonical-unit and operationalization states live in the .meta.json histograms beside each ledger — cite those, not a percentage. Tranche closure is decided by unit-dispositionsfully_operationalized, not row counts; tranche-001.json pins the SHA-256 of every input it closed against.
2.10 FUSHA-BENCH
what it is
A frozen, deterministic authority-integrity baseline over four independent axes (ownership geometry, structured hover, contextual translation, tutor runtime). Gold is admitted only through the certification store's effective state, and every input artifact is SHA-256 pinned. It measures whether frozen certified facts and runtime probes pass their bounded contracts — not model or learner accuracy.
tools/fusha_bench.py (fail-closed; writes only with explicit --write)
validator
tools/test_fusha_bench.py
sibling
eval/rm40/ (morphology-generation lane manifest + model card)
state
v1 frozen. aggregate_score_allowed: false — the axes have different denominators, so no aggregate score exists; contextual translation stays unscored until the repo holds certified contextual-translation gold. The quarantine list keeps tutor probes separate from anything that could leak into them.
3. The data flow
qamus/data/current/entries.jsonl [LIVE — exported, gated]
|
+--> largelexicon lemma/form/stem + qword tables [LIVE build / CANDIDATE output]
v
lattice/example-ayah-universe.jsonl (+ .occurrences) [LIVE — occurrence identity]
v
lattice/particle-occurrence-matrix.jsonl [CANDIDATE ONLY — no row certified]
v
p007-population-classification -> p007-reverse-universe [LIVE dispositioning, p007 only]
+----+---------+------------------+-------------+-----------+
v v v v v
rejected geometry lane direct-source two-vote scholar
(closed) (CERTIFIED: function queue queue queue
geometry only) [CANDIDATE] [CANDIDATE] [BLOCKED]
v
tools/certify_typed_fact.py -> hash-chained events [LIVE — fact-level, revocable]
v
typed edges (one graph, 31 edge types) [LIVE for certified facts]
v
two-surface projection: ONE artifact -> rich-at-rest + rich-hover
v [LIVE for the p007 pilot only]
parity validation (same projection hash everywhere)[LIVE — harness-gated]
v
qamus.website_projection_payload.v1 [SAMPLES ONLY — 9 committed]
X ------------------------------------> qamus.dawah.wiki
LIVE_QAMUS_MUTATION: NOT_AUTHORIZED (owner-gated deploy rung; the website
agent renders, never authors)
readback / dogfood: defects -> fixtures -> rules -> skill increments [LIVE]
+--> curriculum absorption -> canonical units -> tranches -> drills [CANDIDATE]
LIVE = built, validated and gated by tools/check_regressions.py here. CANDIDATE = the
artifact exists and is honest about being uncertified. The deploy edge is owner-gated: nothing
certified in this repo is deployed, and no autonomous deployment path exists.
4. Who consumes what
consumer
what it consumes
contract file
Tutor runtime (a dispatcher, not a skill)
candidate lattices, typed facts, gate tiers, KC catalog, CEFR band
On any conflict between an issue checkbox and a ledger, the ledger wins. Qamus issues close only
when the repo ledgers and the live site both reflect the closed state — so while the deploy rung is
shut, the honest closing comment is "candidate-complete, awaiting deploy window".
5. What is deliberately not here
absent
why
where it lives instead
Live app code — templates, CSS, JS, deployed pages
WEBSITE_FRONTEND: OWNED_BY_THE_SEPARATE_WEBSITE_AGENT; Fusha never edits renderer files
the website agent's tree; the payload contract is the entire interface
Any live-mutation path
LIVE_QAMUS_MUTATION: NOT_AUTHORIZED (docs/INDEX.md §2); every apply is a separate owner-gated step
owner-gated deploy windows
Source-site lesson prose, exercises, answer keys — and the source site's name
clean-room custody: only hashes, counts, labels and independently authored derivations are committed
External gloss, translation, tafsīr or OCR text; raw corpora dumps
only the repo's own authored output ({"src":"qamus","kind":"authored","lang":"en"}) is ever public; external material is private triangulation evidence
the private evidence plane (docs/evidence-custody.md)
Secrets, server topology, private paths, packet contents, deploy receipts
public repo; evidence in public text = repo paths, PR numbers, blocker ids
private workspace
Model weights, large OCR dumps, generated full manifests
regenerable; committed baselines carry the full output's row count + sha256 instead
the ignored out/ tree
Custody in one line: what may be committed, what must stay private, and how to cite evidence
publicly are governed by CONTRIBUTING.md, with the enforceable detail in
provenance/source-boundaries.md and docs/evidence-custody.md.
6. Directory census (top level — complete against git ls-tree, audited 2026-08-05)
Every top-level entry, its purpose, and its primary consumer. Verdicts from the 2026-08-05
organization audit; the pending-disposition items it opened were closed by the 2026-08-05 hygiene
batch and now carry their disposition inline. docs/INDEX.md carries the cold-reader subset.
Entry
Purpose
State
sarf/, nahw/
The canonical skill engines (SKILL.md + procedures/rules/references/evals)
active
skills/
~2KB installable wrappers deferring to the engines; hash-tracked in skills/registry/skill-mirror-map.json
The parser/morphology substrate plane (lexicon/morphology/parser schemas, fixtures, model cards) — distinct from qamus/; name collision with the repo is historical
Implementation evidence records — known gap: 12/22 referenced evidence addresses live in the operator workspace, not the clone (open; also flagged in docs/INDEX.md)
active, gap flagged
research/
One companion file to the Qurʾānic-anchor charter
folded into docs/ 2026-08-05 — now docs/QURANIC-ANCHOR-EVALUATION-PLAN.md; the directory no longer exists
attic/
Deliberate archive with per-file retirement evidence and restore procedure (D-11 pattern)
deliberate-archive
prep/, .IMPLEMENTAUDIT/
Closed one-shot migration staging + committed skill scratch state
mostly retired to attic/ 2026-08-05 — attic/prep/ (5 zero-consumer files) + attic/IMPLEMENTAUDIT-runs/; .IMPLEMENTAUDIT/ is now gitignored. prep/ survives holding exactly one live file, morphline-approved-manifest.json, which tools/apply_rm20_morphline.py + two other tools read
root data artifacts (fd*, vn-*, PROOFN-MANIFEST.json)
Consumed calibration/ledger inputs
relocated to qamus/reports/ 2026-08-05 — calibration-455/, proofn/, and the vn-* trio at qamus/reports/; every consumer re-pointed
.github/, .gitattributes, .gitignore
CI workflow gate, byte-stability policy (*.jsonl text eol=lf keeps sha256 pins platform-stable), ignore rules