QLens Foundation Book¶

Publication: PUB-000001 · First canonical QLens publication

Preface¶

Most knowledge systems are optimized for publication. They store the polished answer, the approved policy, the current model, or the final report. This is useful, but incomplete. Once the answer has been separated from the path that produced it, later readers cannot reliably inspect what was observed, what was inferred, what remained uncertain, what alternatives were rejected, or why a revision became necessary.

QLens was conceived to preserve that missing path.

It is not merely a note-taking format, a documentation theme, a database schema, or a command-line application. Those are implementations. QLens is first a discipline: a way to let evidence challenge understanding while preserving the history of that challenge.

This Foundation Book states that discipline in durable terms. It is intentionally implementation-independent. A future QLens may use different storage engines, interfaces, programming languages, or presentation systems. It remains QLens only while it preserves the commitments described here.

The Invitation¶

Reality quietly asks:

Will you follow, even if it costs your favorite idea?

The researcher answers:

Yes.

That answer is the beginning of QLens.

The invitation is not to become certain more quickly. It is to become more honest about what is known, how it is known, and what could still overturn it. QLens asks the researcher to distinguish observation from interpretation, evidence from preference, and current understanding from Reality itself.

The cost is real. A cherished explanation may fail. A confident conclusion may need revision. A long-standing vocabulary may prove inadequate. QLens treats such correction not as defeat, but as evidence that the research process remains alive.

The Research Covenant¶

A QLens research space is governed by the following covenant:

Reality is the authority. No document, person, institution, model, or tool outranks Reality.
Understanding is provisional. Even verified work remains open to correction by better evidence or reasoning.
Evidence is preserved. Conclusions may change; the evidential record must remain inspectable.
Reasoning is exposed. Important inferential steps must not be hidden behind authority or presentation.
Uncertainty is recorded. Unknown, unresolved, disputed, and weakly supported states are legitimate research states.
Revision is traceable. Correction must preserve what changed, why it changed, and what it replaced.
Identity is stable. Research objects retain stable identities even when titles, files, or locations change.
Presentation is subordinate. A beautiful interface may clarify knowledge, but cannot define it.
Automation has limits. Software may validate structure and consistency, but cannot certify truth.
Stewardship outlives authorship. A research space must remain understandable to people who did not create it.

This covenant is not decorative. Every schema, contract, command, interface, and governance decision should be tested against it.

Reality Is the Authority¶

QLens begins by separating three things that are often collapsed:

Reality: what is.
Evidence: what becomes available for examination.
Understanding: the model formed by interpreting evidence.

Reality does not become true because a repository records it. A model does not become real because a committee approves it. A conclusion does not become immune from correction because it has been published.

This distinction establishes the direction of authority:

Reality → Evidence → Reasoning → Understanding

The arrow must never be reversed. Researchers may select evidence poorly, reason incorrectly, or overstate a conclusion. Reality is not obligated to conform.

Therefore QLens does not describe itself as a system of truth storage. It is a system for preserving accountable attempts to understand Reality.

Reality and Representation¶

Every research object is a representation. A statement, table, image, measurement, quotation, model, or narrative is not the thing itself. It is a mediated record created under particular conditions.

This matters because representations can fail in different ways:

an observation may be incomplete;
a measurement may be inaccurate;
a source may be misquoted;
a classification may impose the wrong categories;
a model may explain one region of evidence while failing elsewhere;
a polished summary may conceal unresolved conflict.

QLens therefore preserves context around representations: provenance, status, relationships, verification, and revision history. The goal is not to eliminate mediation. That is impossible. The goal is to make mediation visible enough to examine.

Understanding Must Remain Correctable¶

Correctability is the defining property of a living research system.

A system is not correctable merely because files can be edited. It is correctable when it can:

identify the current understanding;
show the evidence and reasoning that support it;
receive conflicting evidence without suppressing it;
compare alternative explanations;
revise the current understanding;
preserve the superseded understanding and the reason for change.

QLens therefore treats revision as part of knowledge, not as clerical history. A corrected conclusion without its revision path is less informative than it appears, because future researchers cannot see which failure was discovered or whether the same failure is returning.

Stability and correctability are not opposites. Stable identity, explicit lifecycle states, and preserved history make responsible correction possible.

The Cost of Uncorrectable Knowledge¶

Uncorrectable knowledge systems accumulate authority while losing contact with their own foundations. Typical symptoms include:

conclusions detached from evidence;
outdated claims retained because changing them is socially expensive;
disagreements hidden in private discussion;
revisions overwritten without explanation;
institutional confidence mistaken for evidential strength;
interfaces that display certainty the underlying research does not possess.

The cost is not only intellectual. Decisions, systems, policies, and people may depend on claims whose support can no longer be inspected.

QLens addresses this by making the path of understanding part of the canonical record. The record may still contain error, but the error has somewhere to be found, challenged, and revised.

From Curiosity to a Research Question¶

Research begins when curiosity is disciplined into a question.

A useful question identifies what remains unresolved without smuggling in the desired answer. It should be specific enough to guide evidence collection, yet open enough to permit correction of the assumptions that produced it.

In QLens, a question is a first-class object because questions have history. They can be refined, divided, related, answered provisionally, reopened, or superseded. The original wording may reveal assumptions that later research exposes.

A question object should therefore preserve:

the question itself;
its context and scope;
its present status;
relationships to observations, evidence, and other questions;
any revision that materially changes what is being asked.

Observation Before Explanation¶

An observation records what was noticed before the research space decides what it means.

This separation is difficult because perception arrives already shaped by language, expectations, and prior models. QLens does not pretend that observation is perfectly neutral. Instead, it requires the researcher to minimize interpretive loading and to make unavoidable framing explicit.

Compare:

“The service failed because the database was overloaded.”
“At 14:03, requests returned HTTP 503 while database CPU was reported at 98%.”

The first is an explanation. The second is closer to an observation. Both may be useful, but they belong in different objects so that the explanatory claim can be challenged without discarding the observed record.

Verification and Source Discipline¶

Verification records how an observation, source, transcription, measurement, or derived claim was checked.

Verification does not mean absolute proof. It means that a defined check was performed and its outcome was preserved. Examples include reproducing a measurement, comparing a quotation with the primary source, checking a file checksum, confirming a date from an authoritative record, or independently repeating an analysis.

A verification object should distinguish:

what was checked;
by which method;
against what reference;
with what result;
under what limitations.

This creates a crucial separation between “I believe this source” and “this specific property was checked in this specific way.”

Evidence Is Contextual¶

Evidence is not a free-floating fact. Something becomes evidence in relation to a question, claim, or model.

The same observation may support one proposition, weaken another, and remain irrelevant to a third. QLens therefore records relationships rather than treating evidence as a universal label.

Good evidence records preserve:

the underlying observation or source;
provenance and acquisition context;
verification state;
the proposition or question to which it is relevant;
limits on what it can support;
conflicts with other evidence.

Evidence should not contain more certainty than its source permits. A weak source remains weak even when it supports a preferred conclusion.

Absence, Conflict, and Negative Evidence¶

Research often fails when it records only confirming material.

QLens requires space for:

observations that do not fit the current model;
failed attempts to reproduce a result;
expected evidence that was not found;
sources that directly conflict;
boundary cases that weaken a generalization.

Absence must be handled carefully. “Not observed” does not automatically mean “does not exist.” Its evidential force depends on whether the research method should have detected the thing if it were present.

Conflict should not be prematurely resolved by deleting one side. Competing evidence remains visible until the research can explain the disagreement or honestly preserve it as unresolved.

Reasoning as a First-Class Object¶

Many repositories preserve sources and conclusions but omit the bridge between them. QLens makes that bridge explicit.

A reasoning object records how selected evidence is used to support, weaken, distinguish, or revise an explanation. It may contain deductive, inductive, abductive, comparative, causal, statistical, or interpretive reasoning, provided the inferential steps are inspectable.

Reasoning should identify:

the inputs it depends on;
the inference being made;
assumptions required for that inference;
alternatives considered;
limitations and possible failure modes;
the understanding or decision it supports.

The purpose is not to make every thought verbose. It is to prevent important conclusions from appearing without an accountable path.

Assumptions and Inference¶

No research is assumption-free. The danger lies in assumptions that operate invisibly.

QLens distinguishes at least three forms:

Method assumptions — what a method presumes about measurement, language, causality, or sampling.
Context assumptions — what is presumed about the situation being studied.
Inference assumptions — what must be true for evidence to support a conclusion.

Assumptions should be recorded where their failure would materially change the outcome. They may later become questions or targets of verification.

An honest reasoning record does not merely state why a conclusion seems plausible. It also states what would make the inference fail.

Explanatory Models¶

An explanatory model organizes observations and evidence into a coherent account of how or why something occurs.

Models are useful because isolated facts do not explain themselves. Models are dangerous because coherence can be mistaken for truth.

QLens therefore allows multiple explanatory models to coexist. Each model may record:

its central claim;
the domain it attempts to explain;
supporting and conflicting evidence;
assumptions;
predictions or consequences;
known limitations;
relationships to competing models.

A model should not be promoted merely because it is elegant. It earns strength by surviving contact with evidence and by explaining more with fewer unsupported assumptions.

Current Understanding, Not Final Truth¶

A QLens research space needs a readable statement of where the investigation currently stands. That is the role of the current-understanding object.

It is neither a dump of every note nor a declaration of final truth. It is a versioned synthesis that states:

what is presently understood;
which evidence and reasoning support it;
the strength and limits of that support;
what remains unresolved;
which earlier understanding it supersedes, if any.

The phrase “current understanding” is deliberate. It allows decisive action where necessary without pretending that inquiry has ended.

Uncertainty Is Information¶

Uncertainty is not empty space around knowledge. It is information about the state of inquiry.

QLens should be able to distinguish:

not yet investigated;
insufficient evidence;
conflicting evidence;
ambiguous interpretation;
method limitation;
unresolved scope;
low-confidence inference;
genuine indeterminacy.

Collapsing all of these into “unknown” loses important guidance. Conversely, assigning a precise numerical confidence without a defensible method creates false rigor.

The research space should express uncertainty at the level justified by the work. Honest ambiguity is more valuable than decorative precision.

Why Repository First¶

QLens is repository-first because durable research requires more than a conversation or a rendered page.

A repository provides:

canonical files that can be inspected directly;
stable version history;
reviewable changes;
reproducible validation;
portability across tools;
separation between content and presentation;
continuity beyond the memory of individual researchers.

Repository-first does not mean interface-last. Interfaces may make research dramatically easier. It means that the interface must write to and read from a canonical structure that remains accessible without the interface.

The repository is not merely a storage location. It is the durable research space.

Canonical Source and Derived Views¶

A trustworthy system must know where canonical meaning lives.

In QLens, canonical research content belongs to repository objects and their governed metadata. Search indexes, rendered HTML, graphs, dashboards, caches, embeddings, and AI-generated summaries are derived views.

Derived views may be rebuilt. They may be wrong. They may omit context. They must not silently become the source of record.

This principle prevents a common failure: a convenient representation gradually acquiring authority that belongs to the underlying evidence and objects.

Stable Identity Through OIDs¶

Files move. Titles improve. Folders are reorganized. Presentation changes. Identity must survive all of them.

QLens assigns each canonical object an object identifier, or OID. The OID is the durable identity of the object. A path is only its present location.

Stable identity enables:

reliable relationships across reorganizations;
unambiguous revision history;
duplicate detection;
references from external systems;
long-lived citations within the research space.

OID stability is therefore not a convenience. It is a prerequisite for traceability.

Relationships and the Research Graph¶

Research objects gain meaning through relationships.

A question is investigated by observations. Evidence is derived from or linked to sources. Reasoning uses evidence. A model explains observations. A current understanding synthesizes reasoning. A revision supersedes an earlier state.

These relationships form a research graph. The graph is not merely a visualization. It is the structure that allows the repository to answer questions such as:

Which evidence supports this understanding?
Which conclusions depend on this disputed source?
What changed after this verification failed?
Which questions remain open?
What would be affected if this assumption were rejected?

The graph should be generated from canonical relationships, not maintained as a competing source of truth.

History Without Erasure¶

QLens rejects the idea that correction requires pretending the earlier state never existed.

When an understanding changes, the repository should preserve:

the superseded object or revision;
the new evidence or reasoning;
the explicit relationship between old and new;
the date and steward of the change;
unresolved consequences of the revision.

Preserved history serves accountability, learning, and error prevention. It also protects researchers from false accusations of inconsistency: responsible research is expected to change when warranted.

Erasure hides the process. Revision reveals it.

The Canonical Object Family¶

The reference repository defines ten canonical object types:

Object	Primary role
`research_space`	Governs the scope and identity of an investigation
`question`	Records what is being asked
`observation`	Records what was noticed or measured
`verification`	Records how something was checked
`evidence`	Records relevance to a question, claim, or model
`explanatory_model`	Proposes a coherent account
`reasoning`	Exposes inferential steps
`current_understanding`	States the present synthesis
`relationship`	Connects canonical objects
`monologue`	Presents a human-readable reflective narrative

These types are not arbitrary folders. Together they separate roles that are frequently mixed in ordinary notes. The separation makes disagreement and revision more precise.

The Research Space¶

The research space is the central unit of QLens.

It defines the investigation’s scope, governing question or domain, vocabulary, participants or stewards, lifecycle, and canonical relationships. It provides a boundary within which objects can be interpreted without assuming the entire repository shares the same context.

A research space should be large enough to preserve meaningful continuity, but small enough that its questions and evidence remain coherent. Separate spaces may be related when research crosses boundaries.

The research space is not a folder name. It is a canonical object with identity and governance.

Monologue and Public Understanding¶

Research needs rigorous internal objects, but people also need coherent narrative.

The monologue object translates a body of research into reflective, human-readable form while retaining links to the canonical objects from which it was derived. It may explain the path of inquiry, reveal changes in understanding, or communicate the present synthesis to a wider audience.

A monologue is not the canonical source of the evidence it presents. It is a governed presentation object. When narrative clarity requires compression, the underlying relationships must remain available for inspection.

This separation allows QLens to support public communication without letting rhetoric replace research structure.

Object Contracts¶

Each object type has a contract describing its purpose, required fields, valid relationships, lifecycle expectations, and boundaries.

Contracts answer semantic questions that a schema alone cannot fully express:

What is this object for?
What must it not be used for?
Which relationships are meaningful?
What evidence is required before status changes?
Which fields carry canonical meaning?

Schemas validate machine-readable structure. Contracts preserve human-readable intent. Both are needed because structurally valid data can still misuse an object type.

Lifecycle of a Research Object¶

Objects evolve through explicit states. The reference lifecycle includes states such as draft, collecting, review, verified, superseded, and archived, according to object contract.

Lifecycle states communicate process, not truth. “Verified” means required checks have been completed under the contract; it does not mean metaphysical certainty. “Draft” does not mean useless; it means the object has not completed later review obligations.

Transitions should be evidence-bearing actions. A status change may require verification, reviewer identity, timestamps, or relationships to replacement objects.

Explicit lifecycle prevents polished appearance from being mistaken for research maturity.

Revision and Supersession¶

Minor edits and conceptual revisions are not the same.

Spelling corrections, formatting, and clarified wording may update an object without changing its intellectual claim. A material change to evidence, reasoning, model, or understanding should create a traceable revision or superseding object according to contract.

Supersession does not declare the earlier object worthless. It states that another object now occupies its former role. The relationship should explain why.

Good revision practice preserves continuity while preventing outdated material from masquerading as current.

Review and Verification¶

Review evaluates whether an object fulfills its contract, uses evidence responsibly, exposes assumptions, and represents uncertainty honestly.

Verification checks defined properties. Review judges the adequacy and integrity of the work within a stated scope. Neither should be reduced to a checkbox.

A robust review may ask:

Are sources represented accurately?
Are contrary observations included?
Does the reasoning actually follow?
Are assumptions visible?
Is the current understanding stronger than the evidence permits?
Would a future steward understand what remains unresolved?

The result of review should itself be traceable when it materially affects lifecycle.

Archiving Without Disappearance¶

Archiving removes an object from active work without deleting its research value.

An archived object may be obsolete, out of scope, replaced, or no longer maintained. Its archived state should state why and, when relevant, point to the active replacement.

Deletion should be exceptional and governed, especially for objects that have been cited or used in reasoning. A repository that silently deletes inconvenient history cannot provide dependable traceability.

Repository Integrity Rules¶

Repository integrity is the minimum condition for trustworthy navigation of the research record.

Structural integrity includes:

unique OIDs;
valid object types;
resolvable relationships;
required metadata;
valid lifecycle values;
consistent timestamps;
schema-conformant objects;
no competing canonical copies;
documentation navigation that resolves.

These rules do not prove that an understanding is true. They ensure that the repository can reliably represent what it claims to contain.

What Validation Can and Cannot Do¶

Validation can detect malformed identifiers, missing fields, duplicate identities, invalid relationships, broken navigation, or lifecycle inconsistencies.

Validation cannot determine whether:

an observation is honest;
a source is ultimately reliable;
an inference is philosophically sound;
a model corresponds to Reality;
a conclusion is morally wise.

QLens tooling must never blur this boundary. A green validation result means the repository passed defined structural checks. It is not a certificate of truth.

This limitation is a strength because it prevents automation from claiming authority it does not possess.

Governance and Stewardship¶

A durable research space needs stewardship rules.

Stewards protect object identity, lifecycle discipline, review quality, and continuity. They do not own Reality and should not become gatekeepers who suppress correction.

Governance should define:

who may create and revise objects;
what review is required for status transitions;
how conflicts are recorded;
how vocabulary changes are introduced;
how breaking contract changes are versioned;
how abandoned research spaces are maintained or archived.

Good governance protects openness to correction while preventing careless mutation of the record.

Disagreement Without Fragmentation¶

QLens should preserve meaningful disagreement inside the research graph instead of forcing premature consensus or creating disconnected copies.

Competing models, conflicting evidence, and alternative reasoning paths can coexist when their relationships and statuses are explicit. This allows the repository to show not only that disagreement exists, but where it exists.

Forking may sometimes be necessary, especially when governance or scope diverges. Even then, shared OIDs, provenance, and explicit lineage should preserve the relationship between histories where possible.

The goal is not harmony. The goal is inspectable disagreement.

The CLI as Repository Guardian¶

The QLens command-line interface exists to make correct repository behavior easier and invalid behavior harder.

Its responsibilities include:

generating valid OIDs;
scaffolding contract-compliant objects;
validating objects and repositories;
reporting structural health;
supporting reproducible automation.

The CLI should not become an oracle. It must not decide whether an explanation is true or whether evidence is persuasive. Those remain research responsibilities.

A good CLI protects invariants while leaving judgment visible and human-accountable.

NUR and the Presentation Boundary¶

NUR is the presentation layer for reading and working with QLens material. It may improve typography, navigation, metadata visibility, research context, and responsive behavior.

NUR must remain additive. It may reveal canonical meaning, but must not invent or silently alter it. The same repository should remain understandable through raw Markdown and structured objects even if NUR is unavailable.

This boundary protects portability and prevents visual design from becoming an undocumented semantic dependency.

AI and Automation¶

AI can assist QLens by locating relationships, proposing summaries, identifying possible conflicts, generating drafts, or suggesting questions. These outputs are valuable only when their status and provenance are explicit.

AI-generated material must not silently enter the canonical record as verified understanding. It should be treated as a proposal, draft, or derived view until reviewed under the same standards applied to human work.

The governing principle is simple:

Automation may accelerate inquiry, but it may not inherit the authority of Reality.

QLens should make AI assistance inspectable rather than invisible.

Portability and Longevity¶

A research space may outlive its current software stack.

QLens therefore favors open, inspectable, text-friendly formats and explicit contracts. The repository should remain recoverable without a proprietary service. Derived indexes and interfaces should be rebuildable from canonical content.

Longevity also requires semantic versioning of contracts and migrations that preserve identity and history. A future implementation may change nearly everything about storage or display, but it must be able to explain what happened to every canonical object.

Starting a Research Space¶

A new research space should begin with restraint.

State the domain and boundary.
Create the governing research-space object.
Record the initiating question without forcing a conclusion.
Define only the vocabulary needed to begin.
Capture observations and sources separately from explanation.
Record early assumptions and uncertainties.
Establish stewardship and review expectations.

The aim is not to design the entire ontology before research begins. It is to create enough structure that the first correction can be preserved responsibly.

The Operating Cycle¶

A typical QLens operating cycle is:

Question
  ↓
Observation and source collection
  ↓
Verification
  ↓
Evidence relationships
  ↓
Competing explanatory models
  ↓
Reasoning and review
  ↓
Current understanding
  ↓
New question, revision, or supersession

The cycle is not always linear. New observations may expose a bad question. Verification may invalidate evidence. A model may generate predictions that create new observations. The repository graph should represent the actual path rather than forcing research into an artificial sequence.

Writing a Current Understanding¶

A strong current-understanding object should be readable without hiding its dependencies.

It should:

answer the active question as directly as the evidence permits;
distinguish observation from inference;
cite supporting reasoning and evidence objects;
state important conflicts and limitations;
avoid universal claims outside the investigated scope;
identify open questions;
record the understanding it supersedes.

The writing should be clear enough to guide action and cautious enough to remain honest.

Correcting the Record¶

When new evidence conflicts with the current understanding, the research space should not reinterpret the evidence merely to protect the conclusion.

The correction process is:

preserve the conflicting observation or evidence;
verify the conflict where possible;
identify which reasoning or assumption is affected;
revise or replace the explanatory model;
create a new current understanding;
explicitly supersede the earlier state;
update derived narratives and views;
preserve unresolved consequences as open questions.

The integrity of QLens is demonstrated most clearly when it corrects itself.

What QLens Is Not¶

QLens is not:

a machine for producing certainty;
a substitute for domain expertise;
a guarantee that sources are honest;
a philosophical proof that Reality is fully knowable;
a workflow that eliminates disagreement;
a user interface that owns canonical meaning;
an AI system that decides truth;
a rigid ontology that cannot evolve.

QLens is a disciplined environment for preserving accountable, correctable understanding.

The Future of Correctable Knowledge¶

The long-term ambition of QLens is not to centralize all knowledge. It is to make research spaces more honest, portable, inspectable, and capable of correction.

Future capabilities may include richer graph exploration, collaborative review, semantic querying, provenance-aware AI assistance, distributed research spaces, reproducible evidence pipelines, and stronger migration tooling.

Every capability must pass the same test:

Does it help understanding follow evidence while preserving identity, uncertainty, reasoning, and revision history?

Features that weaken that discipline do not advance QLens, however impressive they appear.

The Final Commitment¶

QLens makes no promise that its current understanding is final.

It makes a different promise:

that evidence will not be hidden to protect a preferred conclusion;
that reasoning will remain open to inspection;
that uncertainty will not be disguised as certainty;
that correction will preserve history;
that tools will not claim the authority of Reality;
that future stewards will be able to see how understanding changed.

The final commitment of QLens is therefore not to permanence of conclusion, but to permanence of intellectual honesty.

We will correct our understanding—not Reality.

Principles at a Glance¶

Foundational¶

Reality is the authority.
Research changes understanding, not Reality.
Understanding must remain correctable.
Intellectual honesty is the core discipline.

Research¶

Separate observation, verification, evidence, reasoning, and understanding.
Preserve conflicting and negative evidence.
Record assumptions and uncertainty.
Allow competing models.

Repository¶

Maintain one canonical source.
Give every canonical object a stable OID.
Preserve relationships and revision history.
Treat rendered pages and indexes as derived views.

Tooling¶

Validate structure, identity, and consistency.
Never present validation as truth certification.
Keep presentation additive.
Keep AI assistance explicit and reviewable.

Reading Map¶

Need	Recommended chapters
Understand the philosophy	Parts I and III
Start a research project	Part IX
Design repository objects	Parts IV and V
Define review and lifecycle	Parts VI and VII
Build tooling or interfaces	Part VIII, then Architecture and Implementation
Evaluate whether a feature belongs in QLens	Covenant, Validation Boundaries, Final Commitment

The Foundation explains why. The Specification defines what. The Architecture organizes how responsibilities are separated. The Implementation documents how this repository realizes them today.