An open protocol for publishing, exchanging, and applying user-owned interpretation layers.
Specification draft v0.1 · Documentation CC-BY 4.0 · Code Apache-2.0 · Status: public draft for discussion
Every era of cheaper information creation has forced society to invent a new quality gate. Books got publishers and editors. The web got search engines. Social media got platform recommendation algorithms. Generative AI has collapsed the cost of producing plausible content — and the gate for this era is still unresolved.
LensPub's proposal is that the next quality gate should belong to the individual, not the platform. Every person should own, inspect, modify, version, and share their own interpretation layer: a portable policy — a lens — that decides what gets highlighted, summarized, flagged for missing evidence, or paired with counterpoints as they read, applied by an engine that runs locally by default, explains every decision it makes, and never changes silently.
LensPub standardizes that layer. It is not a truth engine, not censorship software, not a recommendation algorithm, and not tied to any AI vendor or browser. Original content is never rewritten — interpretation is layered above it, never substituted for it.
A Lens Manifest is the exchange object: a declarative, model-agnostic policy document expressing what you care about — topic priorities, source trust, evidence requirements, presentation preferences — never model weights, never a prompt, and structurally free of your browsing history. A Lens Engine (rule-based, local-model, hosted-model, or hybrid) compiles the manifest and overlays annotations on rendered content, anchored using the W3C Web Annotation vocabulary, each carrying a reasoning trace ("why am I seeing this?") and a reproducibility envelope recording exactly what produced it. Lenses evolve only through a proposal workflow — explicit feedback accumulates into reviewable change proposals under user-set adaptation policies (Locked → Explorer) — and every accepted change is a new version you can diff and roll back. Published lenses (expert, organization, partner) are signed with W3C Verifiable Credentials and composed as subscriptions that advise your lens but never override it.
New here? Read these in order:
- Vision — the thesis and what the world looks like if this works
- Problem Statement — why platform-owned quality gates fail, and why the fix is a protocol
- The worked example — one article, one lens, every annotation explained end to end
- LensPub Protocol — the core specification
| Area | Contents |
|---|---|
constitution/ |
The project constitution — the authoritative design handoff all documents derive from |
docs/ |
Vision · Problem Statement · Design Principles · Prior Art · User Experience · Legal Considerations · Roadmap |
spec/ |
LensPub Protocol · Lens Manifest · Lens Engine · Adaptation Model · Lens Diff |
architecture/ |
Reference Architecture · Reference Implementation |
security/ |
Security Model · Privacy Model · Threat Model |
adr/ |
The ten Architecture Decision Records freezing the constitutional decisions |
schemas/ |
JSON Schemas for the three exchange objects |
examples/ |
Five example manifests, an example diff, and the end-to-end worked example |
poc/ |
Browser proof of concept — a working MV3 extension implementing the rule-based engine tier |
GLOSSARY.md |
Normative vocabulary used across every document |
The proof of concept is a dependency-free Chrome/Chromium extension. Load poc/ unpacked (chrome://extensions → Developer mode), open poc/demo/demo.html, and click any highlight to see the reasoning trace and reproducibility envelope behind it. Instructions: poc/README.md.
The repository's two Node entry points — the schema validator and the engine test suite — need Ajv. Install once (Node 18+):
npm install
Then validate every JSON example against the schemas with npm run validate, and run the engine unit tests with npm test. Both scripts are plain node invocations (scripts/validate-examples.mjs and poc/test/run-tests.mjs) and can be called directly. The extension itself has no dependencies and no build step.
LensPub profiles W3C Web Annotation (overlay anchoring) and W3C Verifiable Credentials 2.0 + DIDs (identity and signing); it complements Solid (optional hosting profile), AT Protocol (reference subscription binding), and C2PA (consumed provenance signal); it replaces nothing. What LensPub itself claims as new is deliberately small: the declarative interpretation-policy object, the parameterized adaptation-governance model, the reproducibility envelope, and the history-free sharing construction. See Prior Art.
This is a v0.1 public draft authored to be discussed, implemented, and criticized. It is a personal open project (GOVERNANCE.md); substantive proposals are welcome as issues (CONTRIBUTING.md). The success criteria are concrete: an engineering team can begin implementation from these documents, multiple independent implementations are possible, and nothing requires reference to a specific AI model.
Documentation and specifications: CC-BY 4.0. Code, schemas, and the proof of concept: Apache-2.0. Details: LICENSE.md.