diff --git a/AGENTS.md b/AGENTS.md
index 4e5ae77..5a0af5a 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -16,4 +16,4 @@ Then submit the final file exactly once after local validation:
scripts/helm-submit output.html --source "your-agent-name"
```
-Run the submission from the target Codex/project root. Helm records that workspace as the artifact's catalog project when the source manifest does not already declare `project`; if needed, pass `--project-id` and `--project-name` explicitly. The command only hands the artifact to the owner's inbox. It does not grant direct access to the browser library. On `409`, keep the prior artifact unchanged and choose a genuinely new stable identity for a new document; on `422`, correct the HDOC contract violation before resubmitting.
+Run the submission from the target Codex/project root. Helm records that workspace as the artifact's catalog project when the source manifest does not already declare `project`; if needed, pass `--project-id` and `--project-name` explicitly. The command only hands the artifact revision to the owner's inbox. It does not grant direct access to the browser library. Keep the same manifest ID when revising the same logical artifact; Helm preserves distinct bytes as immutable revisions and asks the owner before advancing the current version. Use a new ID for a different document or explicit fork. On `422`, correct the HDOC contract violation before resubmitting.
diff --git a/AI-GUIDE.md b/AI-GUIDE.md
index db4d6ae..029c345 100644
--- a/AI-GUIDE.md
+++ b/AI-GUIDE.md
@@ -25,4 +25,4 @@ The shipped templates are the default starting point. Use `research-dossier.html
For a fresh local clone, run [`scripts/helm-agent-bootstrap`](scripts/helm-agent-bootstrap) once. Then write the final `.html` file first and submit that exact file once with [`scripts/helm-submit`](scripts/helm-submit). Run the command from the target project root so the Bridge can attach that workspace to legacy files that do not yet declare `manifest.project`; use `--project-id` and `--project-name` when the working directory is not the target project. Do not send partial drafts. A successful Bridge response means the artifact is ready in the owner's **Agent inbox** for explicit review and import; it does not mean the browser library was changed.
-Never expose the token in a generated artifact, repository, task log, or prompt. On `409 Conflict`, do not overwrite or silently alter the existing document ID. On `422`, fix the reported HDOC contract issue and resubmit the same intended artifact.
+Never expose the token in a generated artifact, repository, task log, or prompt. Reuse the manifest ID only for a revision of the same logical artifact; Helm appends distinct bytes as an immutable Revision and never overwrites the prior source. Use a new ID for a different document or explicit fork. On `422`, fix the reported HDOC contract issue and resubmit the same intended artifact.
diff --git a/README.md b/README.md
index 1111c40..8e3c4d1 100644
--- a/README.md
+++ b/README.md
@@ -18,6 +18,7 @@ Helm keeps finished HTML reports, briefs, dashboards, and research as durable pr
- **Originals remain evidence.** Helm indexes, exports, backs up, and shares the exact HTML bytes; it never silently rewrites the source artifact.
- **Agents have a contract.** `HDOC/1.0`, report templates, and the checked-in agent guide make artifacts portable across projects and agents.
- **The owner keeps control.** Agent output arrives in a reviewable inbox. Browser storage, imports, and intranet publication remain deliberate human actions.
+- **Artifacts have history.** Immutable revisions, Draft / Reviewed / Published state, visual comparison, Fork lineage, and a stable Channel address keep change legible without rewriting evidence.
## Start in one minute
@@ -64,7 +65,7 @@ The final artifact appears in **Agent inbox** for review and explicit import. Re
| Path | Purpose |
| --- | --- |
-| [`index.html`](index.html), [`app.js`](app.js), [`styles.css`](styles.css) | Static browser library, local catalog, safe reader, and interface. |
+| [`index.html`](index.html), [`app.js`](app.js), [`channel-store.js`](channel-store.js), [`styles.css`](styles.css) | Static browser library, Artifact / Revision store, safe reader, and interface. |
| [`validator.js`](validator.js) | Browser-side `HDOC/1.0` inspection and portability warnings. |
| [`helm_bridge.py`](helm_bridge.py) | Loopback-only agent ingress and immutable inbox records. |
| [`helm_share_server.py`](helm_share_server.py) | Static app plus owner-only publication of immutable read-only share links. |
@@ -99,6 +100,7 @@ Helm is intentionally a single-person, local-first archive. It does not provide
- [`docs/AGENT-BRIDGE.md`](docs/AGENT-BRIDGE.md) — Bridge API, security model, and conflict semantics.
- [`docs/LOCAL-ARCHIVE-LAYOUT.md`](docs/LOCAL-ARCHIVE-LAYOUT.md) — portable `HARC/1.0` archive format.
- [`docs/INTRANET-SHARING.md`](docs/INTRANET-SHARING.md) — owner-controlled immutable sharing model.
+- [`docs/CHANNELS.md`](docs/CHANNELS.md) — Artifact, Revision, publication, comparison, and Fork semantics.
## Contributing and security
diff --git a/app.js b/app.js
index e542d3e..461d7ef 100644
--- a/app.js
+++ b/app.js
@@ -1,7 +1,3 @@
-const DB_NAME = 'helm-html-archive';
-const DB_VERSION = 3;
-const STORE = 'documents';
-const SETTINGS = 'settings';
const SCHEMA = 'HDOC/1.0';
const DOCUMENT_TYPES = new Set(['report', 'brief', 'reference', 'dashboard', 'note']);
const PROJECT_ID_PATTERN = /^[a-z0-9]+(?:[a-z0-9-]*[a-z0-9])?$/;
@@ -9,7 +5,8 @@ const UNASSIGNED_PROJECT = Object.freeze({ id: 'unassigned', name: 'Needs projec
const MAX_IMPORT_BYTES = 5 * 1024 * 1024;
const MAX_SEARCH_TEXT = 250000;
const AGENT_BRIDGE_URL = 'http://127.0.0.1:4175';
-const SHARE_API_URL = '/api/share';
+const CHANNEL_API_URL = '/api/channels';
+const channelRepository = globalThis.HelmChannelStore?.defaultRepository;
const templates = [
{ id: 'research-report', title: 'Research dossier', type: 'report', tags: ['research', 'evidence'], summary: 'Question → answer → evidence → recommendation.', accent: '#e7e6df' },
@@ -38,6 +35,7 @@ let appearanceMode = 'system';
let readerArtifactId = null;
let readerLoadToken = 0;
let readerSlowTimer = null;
+const lineageSources = new Map();
const APPEARANCE_MODES = new Set(['light', 'dark', 'system']);
@@ -92,62 +90,48 @@ function knownProjects() {
});
}
-function openDatabase() {
- return new Promise((resolve, reject) => {
- const request = indexedDB.open(DB_NAME, DB_VERSION);
- request.onupgradeneeded = () => {
- const db = request.result;
- if (!db.objectStoreNames.contains(STORE)) db.createObjectStore(STORE, { keyPath: 'id' });
- if (!db.objectStoreNames.contains(SETTINGS)) db.createObjectStore(SETTINGS, { keyPath: 'key' });
- };
- request.onsuccess = () => resolve(request.result);
- request.onerror = () => reject(request.error);
- });
+async function getAll() {
+ if (!channelRepository) throw new Error('Helm Channels repository is unavailable.');
+ const records = await channelRepository.listDocuments();
+ return Promise.all(records.filter(Boolean).map(async (record) => ({ ...record, revisions: await channelRepository.listRevisions(record.id) })));
}
-async function getAll() {
- const db = await openDatabase();
- return new Promise((resolve, reject) => {
- const request = db.transaction(STORE, 'readonly').objectStore(STORE).getAll();
- request.onsuccess = () => resolve(request.result);
- request.onerror = () => reject(request.error);
- });
+async function loadLineageSource(id, seen = new Set()) {
+ if (!id || seen.has(id) || documents.some((artifact) => artifact.id === id) || lineageSources.has(id)) return;
+ seen.add(id);
+ const document = await channelRepository.getDocument(id);
+ if (!document) return;
+ const source = { ...document, revisions: await channelRepository.listRevisions(id) };
+ lineageSources.set(id, source);
+ if (source.forkedFrom) await loadLineageSource(source.forkedFrom.artifactId, seen);
+}
+
+async function loadRequiredLineageSources() {
+ for (const artifact of documents) {
+ if (artifact.forkedFrom) await loadLineageSource(artifact.forkedFrom.artifactId);
+ }
}
async function saveDocument(artifact) {
- const db = await openDatabase();
- return new Promise((resolve, reject) => {
- const request = db.transaction(STORE, 'readwrite').objectStore(STORE).put(artifact);
- request.onsuccess = () => resolve();
- request.onerror = () => reject(request.error);
+ const existing = await channelRepository.getArtifact(artifact.id);
+ const result = await channelRepository.createOrRevise(artifact, {
+ artifactId: artifact.id,
+ expectedCurrentRevisionId: existing?.currentRevisionId,
+ updateCatalog: Boolean(existing)
});
+ return { ...result.document, revisions: await channelRepository.listRevisions(artifact.id) };
}
-async function removeDocument(id) {
- const db = await openDatabase();
- return new Promise((resolve, reject) => {
- const request = db.transaction(STORE, 'readwrite').objectStore(STORE).delete(id);
- request.onsuccess = () => resolve();
- request.onerror = () => reject(request.error);
- });
+async function removeDocument(id, { hard = true } = {}) {
+ return channelRepository.deleteArtifact(id, { hard });
}
async function getSetting(key) {
- const db = await openDatabase();
- return new Promise((resolve, reject) => {
- const request = db.transaction(SETTINGS, 'readonly').objectStore(SETTINGS).get(key);
- request.onsuccess = () => resolve(request.result?.value);
- request.onerror = () => reject(request.error);
- });
+ return channelRepository.getSetting(key);
}
async function setSetting(key, value) {
- const db = await openDatabase();
- return new Promise((resolve, reject) => {
- const request = db.transaction(SETTINGS, 'readwrite').objectStore(SETTINGS).put({ key, value });
- request.onsuccess = () => resolve();
- request.onerror = () => reject(request.error);
- });
+ return channelRepository.setSetting(key, value);
}
function setAppearance(mode, persist = false) {
@@ -272,18 +256,18 @@ function enrichArtifact(record, options = {}) {
async function initialise() {
try {
+ if (!channelRepository) throw new Error('Helm Channels repository is unavailable.');
+ await channelRepository.open();
setAppearance(await getSetting('appearanceMode'));
const stored = await getAll();
const initialized = await getSetting('libraryInitialized');
if (!initialized && !stored.length) {
const seeded = seedDocuments.map((artifact) => ({ ...artifact, html: seedHtml(artifact) }));
- documents = seeded.map((artifact) => enrichArtifact(artifact, { takenIds: new Set() }));
- await Promise.all(documents.map(saveDocument));
+ documents = await Promise.all(seeded.map((artifact) => saveDocument(enrichArtifact(artifact, { takenIds: new Set() }))));
} else {
- const takenIds = new Set();
- documents = stored.map((artifact) => enrichArtifact(artifact.html ? artifact : { ...artifact, html: seedHtml(artifact) }, { takenIds, preserveId: true }));
- await Promise.all(documents.map(saveDocument));
+ documents = stored;
}
+ await loadRequiredLineageSources();
await setSetting('libraryInitialized', true);
archiveFolderHandle = await getSetting('archiveFolderHandle');
selectedId = documents[0]?.id || null;
@@ -361,7 +345,12 @@ function renderLibrary() {
$('#clearLibraryFilters').hidden = !hasActiveLens;
$('#contractReadyCount').textContent = String(readyCount).padStart(2, '0');
$('#librarySourceCount').textContent = String(projectCount).padStart(2, '0');
- $('#documentGrid').innerHTML = filtered.map((artifact, index) => { const project = projectFor(artifact); return `