# Architecture

## Product thesis

Wiki Engine is a compiler with an intermediate representation:

```text
untrusted capture → immutable Source → human-oriented Signal → cross-source Wiki
```

The intermediate Signal layer prevents two common failures: forcing a user to read every raw capture, and exploding each source into many low-value concept pages.

## Authority planes

1. **Source plane** — exact captured bytes live as content-addressed hidden payloads; visible source pages are inert receipts. Semantic tools cannot rewrite payloads through the kernel.
2. **Signal plane** — fallible one-source extraction, explicitly bound to one source ID and digest.
3. **Wiki plane** — fallible cross-source synthesis, explicitly bound to all cited source IDs and digests.
4. **Control plane** — config, registry, records, receipts, revisions, and one writer lock under `.wiki-engine/`.

Signal is not a factual authority. Wiki is not a factual authority. Exact lineage makes review possible; it does not guarantee correctness.

## Why not a YouTube root folder?

Media type is metadata, not the primary authority boundary. YouTube, X, Substack, and websites all enter `Inbox/Web` and become immutable web sources. A source envelope records its kind. Signal and Review can render a YouTube-focused view without fragmenting the source system.

## Video decision ladder

1. Acquire public metadata, description, and the best available timestamped transcript.
2. Extract description URLs without claiming they were inspected.
3. Route transcript-only unless visual evidence could materially change meaning.
4. Request exact cue timestamps for deictic/demo language.
5. Escalate to broad visual review for design/visual-dominant subjects.
6. Write one source-bound Signal note; screenshots are evidence attachments, not source replacements.

The deterministic router is advisory. An agent may escalate but must state why. It may not silently downgrade an explicit user request for visual review.

## Publication contracts

A Signal draft must contain strict frontmatter with its exact `source_id` and `source_sha256`. Video Signals also bind the exact video-manifest and transcript digests. A Wiki draft requires at least two distinct sources and ordered `source_ids`/`source_sha256s`. Kernel publication refuses missing lineage, active Markdown surfaces, collisions, and implicit overwrite. `--supersede` retains the prior record and visible revision under `.wiki-engine/revisions/`.

## Review

Review is read-only. It reports:

- unregistered inbox captures;
- registered duplicates still in Inbox, which can be removed only through exact digest-bound acknowledgement;
- sources missing Signal;
- signaled sources not yet represented in Wiki;
- digest failures through Lint.

Review does not infer truth, merge sources, publish Wiki pages, delete Inbox files, or modify source status. Reading state is a separate explicit mutation. Multi-file publications use an fsynced stage journal and recover on the next mutating command; reads fail closed while recovery is pending.

## OSKA compatibility

Wiki Engine can supply source-owned captures and projections to OSKA, but it does not replace OSKA Source/Evidence/Knowledge contracts. A BIOS bridge must explicitly materialize exact bytes and records before accepting a Wiki claim as governed knowledge.