convolvger 0.1.0__tar.gz

convolvger-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Fahad Bilal Saleem
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

convolvger-0.1.0/PKG-INFO

@@ -0,0 +1,86 @@
+Metadata-Version: 2.4
+Name: convolvger
+Version: 0.1.0
+Summary: Local-first, provider-independent archival for public AI conversations
+Keywords: archival,chatgpt,cli,conversations,digital-preservation
+Author: Fahad Bilal Saleem
+Author-email: Fahad Bilal Saleem <contact@fahadbilal.com>
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: End Users/Desktop
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: System :: Archiving
+Classifier: Typing :: Typed
+Requires-Dist: httpx>=0.28.1
+Requires-Dist: pydantic>=2.13.5
+Requires-Dist: rich>=15.0.0
+Requires-Dist: typer>=0.27.2
+Requires-Python: >=3.12
+Project-URL: Homepage, https://github.com/bilalmughal1/convolvger
+Project-URL: Repository, https://github.com/bilalmughal1/convolvger
+Project-URL: Issues, https://github.com/bilalmughal1/convolvger/issues
+Project-URL: Changelog, https://github.com/bilalmughal1/convolvger/blob/main/CHANGELOG.md
+Description-Content-Type: text/markdown
+
+# Convolvger
+
+Local-first, provider-independent archival for public AI conversations.
+
+Convolvger takes a public AI conversation share URL, reconstructs the conversation into a canonical internal model, validates the extracted data, and exports it into portable formats such as Markdown and JSON.
+
+## Install
+
+or `pip install convolvger`. Requires Python 3.12 or newer.
+
+## Goals
+
+- Archive public AI conversations locally
+- Support multiple AI providers through isolated adapters
+- Preserve conversation structure and exposed content
+- Detect incomplete or inconsistent extraction
+- Produce deterministic, provider-independent output
+- Keep conversion entirely local, with no LLM required
+- Avoid account credentials and telemetry
+
+## What a snapshot is
+
+Convolvger archives *public share snapshots*. A snapshot is what a provider chooses to expose at a given URL at a given moment — not the conversation itself, and not a guarantee.
+
+Share pages can change after they are published. While building the ChatGPT adapter we fetched the same share link twice, eight hours apart. Both responses had the same conversation, the same title, and the same 31 message IDs. Four assistant messages addressed to a tool were served the second time with their payload emptied and their content type relabelled from `code` to `text` — while their IDs, roles, recipients, statuses, weights and every metadata key stayed identical. A comparison of anything but the content would have called the two snapshots the same file. Nothing about the conversation had changed; the provider's rendering of it had.
+
+That is why every Convolvger export records when it was retrieved, reports every message it could not render, and never silently drops content. An archive is a claim about what was there when you looked. It is only trustworthy if it also says when it looked and what it could not see.
+
+Convolvger does not recover private conversations, hidden model state, chain-of-thought, deleted content, or attachments the provider does not publish. If it is not in the snapshot, it is not in the archive.
+
+## Supported Providers
+
+Initial providers:
+
+- ChatGPT
+- Claude
+- Gemini
+- Grok
+
+Additional providers will be added as their public sharing formats are supported and tested.
+
+## Status
+
+Convolvger is under active development and not yet ready for general use.
+
+Working today: `convolvger providers`, `convolvger inspect URL`, `convolvger export URL` with `-o PATH` or `-o -` for stdout, `-f md` or `-f json`, plus `--include-hidden` and `--include-inactive`, and `convolvger verify PATH`.
+
+ChatGPT share links can be fetched, parsed, and exported. Markdown is a reader-facing document that may omit content and reports every omission in its header; JSON is the complete archival record and omits nothing the model holds. The remaining providers are not implemented yet.
+
+Extraction records structured findings, each with a stable code and a level. A note is recorded but does not change the exit status; a warning does. Both are written into the JSON archive either way, so nothing is withheld from the record because it was judged unremarkable.
+
+`convolvger verify PATH` reads a JSON archive and reports what it records, without re-fetching or re-parsing anything. It answers two questions separately: whether the provider served everything its own snapshot structure referenced, and whether everything it served could be modelled. Findings that indicate neither are listed in full and counted toward neither answer, so an archive whose messages are mostly empty by design — which is how a public share snapshot normally arrives — is still reported complete. A finding whose code this version does not recognise changes no answer, since an archive may have been written by a later version. An archive declaring a schema version this version cannot read is refused rather than given a verdict.
+
+Exit codes: 0 clean, 2 completed with warnings, 1 failed. For `verify`, 2 means a check did not pass, and 1 means the file could not be read as an archive at all.
+
+## License
+
+MIT

convolvger-0.1.0/README.md

@@ -0,0 +1,58 @@
+# Convolvger
+
+Local-first, provider-independent archival for public AI conversations.
+
+Convolvger takes a public AI conversation share URL, reconstructs the conversation into a canonical internal model, validates the extracted data, and exports it into portable formats such as Markdown and JSON.
+
+## Install
+
+or `pip install convolvger`. Requires Python 3.12 or newer.
+
+## Goals
+
+- Archive public AI conversations locally
+- Support multiple AI providers through isolated adapters
+- Preserve conversation structure and exposed content
+- Detect incomplete or inconsistent extraction
+- Produce deterministic, provider-independent output
+- Keep conversion entirely local, with no LLM required
+- Avoid account credentials and telemetry
+
+## What a snapshot is
+
+Convolvger archives *public share snapshots*. A snapshot is what a provider chooses to expose at a given URL at a given moment — not the conversation itself, and not a guarantee.
+
+Share pages can change after they are published. While building the ChatGPT adapter we fetched the same share link twice, eight hours apart. Both responses had the same conversation, the same title, and the same 31 message IDs. Four assistant messages addressed to a tool were served the second time with their payload emptied and their content type relabelled from `code` to `text` — while their IDs, roles, recipients, statuses, weights and every metadata key stayed identical. A comparison of anything but the content would have called the two snapshots the same file. Nothing about the conversation had changed; the provider's rendering of it had.
+
+That is why every Convolvger export records when it was retrieved, reports every message it could not render, and never silently drops content. An archive is a claim about what was there when you looked. It is only trustworthy if it also says when it looked and what it could not see.
+
+Convolvger does not recover private conversations, hidden model state, chain-of-thought, deleted content, or attachments the provider does not publish. If it is not in the snapshot, it is not in the archive.
+
+## Supported Providers
+
+Initial providers:
+
+- ChatGPT
+- Claude
+- Gemini
+- Grok
+
+Additional providers will be added as their public sharing formats are supported and tested.
+
+## Status
+
+Convolvger is under active development and not yet ready for general use.
+
+Working today: `convolvger providers`, `convolvger inspect URL`, `convolvger export URL` with `-o PATH` or `-o -` for stdout, `-f md` or `-f json`, plus `--include-hidden` and `--include-inactive`, and `convolvger verify PATH`.
+
+ChatGPT share links can be fetched, parsed, and exported. Markdown is a reader-facing document that may omit content and reports every omission in its header; JSON is the complete archival record and omits nothing the model holds. The remaining providers are not implemented yet.
+
+Extraction records structured findings, each with a stable code and a level. A note is recorded but does not change the exit status; a warning does. Both are written into the JSON archive either way, so nothing is withheld from the record because it was judged unremarkable.
+
+`convolvger verify PATH` reads a JSON archive and reports what it records, without re-fetching or re-parsing anything. It answers two questions separately: whether the provider served everything its own snapshot structure referenced, and whether everything it served could be modelled. Findings that indicate neither are listed in full and counted toward neither answer, so an archive whose messages are mostly empty by design — which is how a public share snapshot normally arrives — is still reported complete. A finding whose code this version does not recognise changes no answer, since an archive may have been written by a later version. An archive declaring a schema version this version cannot read is refused rather than given a verdict.
+
+Exit codes: 0 clean, 2 completed with warnings, 1 failed. For `verify`, 2 means a check did not pass, and 1 means the file could not be read as an archive at all.
+
+## License
+
+MIT

convolvger-0.1.0/pyproject.toml

@@ -0,0 +1,72 @@
+[project]
+name = "convolvger"
+version = "0.1.0"
+description = "Local-first, provider-independent archival for public AI conversations"
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+requires-python = ">=3.12"
+keywords = [
+    "archival",
+    "chatgpt",
+    "cli",
+    "conversations",
+    "digital-preservation",
+]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Environment :: Console",
+    "Intended Audience :: End Users/Desktop",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: System :: Archiving",
+    "Typing :: Typed",
+]
+dependencies = [
+    "httpx>=0.28.1",
+    "pydantic>=2.13.5",
+    "rich>=15.0.0",
+    "typer>=0.27.2",
+]
+
+[[project.authors]]
+name = "Fahad Bilal Saleem"
+email = "contact@fahadbilal.com"
+
+[project.scripts]
+convolvger = "convolvger.cli.main:app"
+
+[project.urls]
+Homepage = "https://github.com/bilalmughal1/convolvger"
+Repository = "https://github.com/bilalmughal1/convolvger"
+Issues = "https://github.com/bilalmughal1/convolvger/issues"
+Changelog = "https://github.com/bilalmughal1/convolvger/blob/main/CHANGELOG.md"
+
+[build-system]
+requires = ["uv_build>=0.12.13,<0.13.0"]
+build-backend = "uv_build"
+
+[tool.ruff.lint]
+select = [
+    "E4",
+    "E7",
+    "E9",
+    "F",
+    "I",
+    "UP",
+    "B",
+    "SIM",
+    "RUF",
+]
+
+[tool.mypy]
+strict = true
+
+[dependency-groups]
+dev = [
+    "mypy>=2.3.1",
+    "pytest>=9.1.1",
+    "pytest-cov>=7.1.0",
+    "ruff>=0.16.7",
+]

convolvger-0.1.0/pyproject.toml.orig

@@ -0,0 +1,61 @@
+[project]
+name = "convolvger"
+version = "0.1.0"
+description = "Local-first, provider-independent archival for public AI conversations"
+readme = "README.md"
+authors = [
+    { name = "Fahad Bilal Saleem", email = "contact@fahadbilal.com" }
+]
+license = "MIT"
+license-files = ["LICENSE"]
+requires-python = ">=3.12"
+keywords = [
+    "archival",
+    "chatgpt",
+    "cli",
+    "conversations",
+    "digital-preservation",
+]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Environment :: Console",
+    "Intended Audience :: End Users/Desktop",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: System :: Archiving",
+    "Typing :: Typed",
+]
+dependencies = [
+    "httpx>=0.28.1",
+    "pydantic>=2.13.5",
+    "rich>=15.0.0",
+    "typer>=0.27.2",
+]
+
+[project.scripts]
+convolvger = "convolvger.cli.main:app"
+
+[project.urls]
+Homepage = "https://github.com/bilalmughal1/convolvger"
+Repository = "https://github.com/bilalmughal1/convolvger"
+Issues = "https://github.com/bilalmughal1/convolvger/issues"
+Changelog = "https://github.com/bilalmughal1/convolvger/blob/main/CHANGELOG.md"
+
+[build-system]
+requires = ["uv_build>=0.12.13,<0.13.0"]
+build-backend = "uv_build"
+
+[tool.ruff.lint]
+select = ["E4", "E7", "E9", "F", "I", "UP", "B", "SIM", "RUF"]
+
+[tool.mypy]
+strict = true
+
+[dependency-groups]
+dev = [
+    "mypy>=2.3.1",
+    "pytest>=9.1.1",
+    "pytest-cov>=7.1.0",
+    "ruff>=0.16.7",
+]

convolvger-0.1.0/src/convolvger/cli/main.py

@@ -0,0 +1,223 @@
+"""Command line interface for Convolvger."""
+
+import re
+import sys
+from pathlib import Path
+from typing import Annotated
+
+import typer
+
+from convolvger.core.archive import ArchiveError, load_archive
+from convolvger.core.errors import ConvolvgerError
+from convolvger.core.findings import Finding, Level
+from convolvger.core.results import ParseError, ParseResult
+from convolvger.core.source import RawSource
+from convolvger.providers.default import build_registry
+from convolvger.renderers import render_json, render_markdown
+from convolvger.validation.report import Report
+
+EXIT_OK = 0
+EXIT_FAILED = 1
+EXIT_WARNINGS = 2
+
+FORMATS = ("md", "json")
+FORMAT_HELP = f"Output format ({', '.join(FORMATS)})."
+
+app = typer.Typer(
+    name="convolvger",
+    help="Archive public AI conversations into portable, provider-independent formats.",
+    no_args_is_help=True,
+)
+
+
+def _slug(title: str | None, fallback: str) -> str:
+    base = (title or fallback).lower()
+    base = re.sub(r"[^a-z0-9]+", "-", base).strip("-")
+    return base[:60] or fallback
+
+
+def _warn(message: str) -> None:
+    typer.echo(message, err=True)
+
+
+def _retrieve(source: str) -> tuple[RawSource, ParseResult]:
+    """Detect, fetch, and parse a conversation source."""
+    registry = build_registry()
+    provider = registry.detect(source)
+    raw = provider.fetch(source)
+    return raw, provider.parse(raw)
+
+
+def _report_findings(findings: list[Finding]) -> None:
+    """Report every finding, loudest first.
+
+    Notes are printed as well as warnings: a note does not change the
+    exit status, but it is still something the snapshot did not carry
+    and the operator should be able to see it.
+    """
+    if not findings:
+        return
+    warnings = [item for item in findings if item.level is Level.WARNING]
+    notes = [item for item in findings if item.level is Level.NOTE]
+    counts = [
+        f"{len(group)} {label}"
+        for group, label in ((warnings, "warning(s)"), (notes, "note(s)"))
+        if group
+    ]
+    _warn(f"\n{', '.join(counts)}:")
+    for item in warnings + notes:
+        where = f" ({item.message_id})" if item.message_id else ""
+        _warn(f"  - [{item.level.value}] {item.code}{where}: {item.message}")
+
+
+def _fail(error: Exception) -> None:
+    _warn(f"Error: {error}")
+    if isinstance(error, ParseError) and error.findings:
+        _report_findings(error.findings)
+    raise typer.Exit(EXIT_FAILED)
+
+
+@app.command()
+def providers() -> None:
+    """List supported conversation providers."""
+    for name in build_registry().names():
+        typer.echo(name)
+
+
+@app.command()
+def inspect(
+    source: Annotated[
+        str,
+        typer.Argument(help="Public conversation URL or local conversation source."),
+    ],
+) -> None:
+    """Inspect a conversation source without exporting it."""
+    try:
+        _, result = _retrieve(source)
+    except ConvolvgerError as error:
+        _fail(error)
+        return
+
+    conversation = result.conversation
+    typer.echo(f"Title:     {conversation.title or '(untitled)'}")
+    typer.echo(f"Provider:  {conversation.provider}")
+    typer.echo(f"Messages:  {len(conversation.messages)}")
+    typer.echo(f"Visible:   {sum(m.visible for m in conversation.messages)}")
+    typer.echo(f"Active:    {sum(m.active for m in conversation.messages)}")
+    typer.echo(f"Blocks:    {sum(len(m.content) for m in conversation.messages)}")
+
+    _report_findings(result.findings)
+    raise typer.Exit(EXIT_WARNINGS if result.warned else EXIT_OK)
+
+
+@app.command()
+def export(
+    source: Annotated[
+        str,
+        typer.Argument(help="Public conversation URL or local conversation source."),
+    ],
+    output: Annotated[
+        Path | None,
+        typer.Option("--output", "-o", help="Output path, or - for stdout."),
+    ] = None,
+    output_format: Annotated[
+        str,
+        typer.Option("--format", "-f", help=FORMAT_HELP),
+    ] = "md",
+    include_hidden: Annotated[
+        bool,
+        typer.Option("--include-hidden", help="Include provider-hidden messages."),
+    ] = False,
+    include_inactive: Annotated[
+        bool,
+        typer.Option("--include-inactive", help="Include deactivated branches."),
+    ] = False,
+) -> None:
+    """Export a conversation to a portable archive."""
+    if output_format not in FORMATS:
+        _warn(f"Error: unsupported format: {output_format}")
+        _warn(f"Supported formats: {', '.join(FORMATS)}")
+        raise typer.Exit(EXIT_FAILED)
+
+    try:
+        raw, result = _retrieve(source)
+    except ConvolvgerError as error:
+        _fail(error)
+        return
+
+    if output_format == "json":
+        if include_hidden or include_inactive:
+            _warn("Note: include flags are ignored; JSON keeps every message.")
+        rendered = render_json(
+            result.conversation,
+            findings=result.findings,
+            fetched_at=raw.fetched_at,
+        )
+    else:
+        rendered = render_markdown(
+            result.conversation,
+            include_hidden=include_hidden,
+            include_inactive=include_inactive,
+            findings=result.findings,
+            fetched_at=raw.fetched_at,
+        )
+
+    if output is not None and str(output) == "-":
+        sys.stdout.write(rendered)
+    else:
+        destination = output or Path(
+            f"{_slug(result.conversation.title, result.conversation.provider)}.{output_format}"
+        )
+        destination.write_text(rendered, encoding="utf-8")
+        _warn(f"Wrote {destination}")
+
+    _report_findings(result.findings)
+    raise typer.Exit(EXIT_WARNINGS if result.warned else EXIT_OK)
+
+
+def _yes_no(value: bool) -> str:
+    return "yes" if value else "no"
+
+
+@app.command()
+def verify(
+    archive: Annotated[
+        Path,
+        typer.Argument(help="Path to a JSON archive written by convolvger."),
+    ],
+) -> None:
+    """Report what a JSON archive says about its own integrity.
+
+    The verdict is derived from the findings the archive already
+    carries. Nothing is re-fetched and nothing is re-parsed: this reads
+    a file and reports what it records.
+    """
+    try:
+        envelope = load_archive(archive.read_text(encoding="utf-8"))
+    except (ArchiveError, OSError) as error:
+        _fail(error)
+        return
+
+    report = Report(findings=envelope.findings)
+    conversation = envelope.conversation
+
+    typer.echo(f"Archive:   {archive}")
+    typer.echo(f"Schema:    {envelope.schema_version}")
+    typer.echo(f"Tool:      {envelope.tool} {envelope.tool_version}")
+    if envelope.retrieved_at is not None:
+        typer.echo(f"Retrieved: {envelope.retrieved_at.isoformat()}")
+    typer.echo(f"Provider:  {conversation.provider}")
+    typer.echo(f"Messages:  {len(conversation.messages)}")
+    typer.echo(f"Complete:  {_yes_no(report.complete)}")
+    typer.echo(f"Faithful:  {_yes_no(report.faithful)}")
+    if report.unrecognised:
+        typer.echo(f"Unknown:   {len(report.unrecognised)} unclassifiable code(s)")
+
+    _report_findings(envelope.findings)
+    raise typer.Exit(
+        EXIT_OK if report.complete and report.faithful else EXIT_WARNINGS
+    )
+
+
+if __name__ == "__main__":
+    app()

convolvger-0.1.0/src/convolvger/core/__init__.py

@@ -0,0 +1,33 @@
+from convolvger.core.archive import ArchiveEnvelope
+from convolvger.core.errors import ConvolvgerError, ProviderNotFoundError
+from convolvger.core.models import (
+    CodeBlock,
+    ContentBlock,
+    Conversation,
+    KnownBlock,
+    Message,
+    MessageRole,
+    ReasoningBlock,
+    TextBlock,
+    UnknownBlock,
+)
+from convolvger.core.results import ParseError, ParseResult
+from convolvger.core.source import RawSource
+
+__all__ = [
+    "ArchiveEnvelope",
+    "CodeBlock",
+    "ContentBlock",
+    "Conversation",
+    "ConvolvgerError",
+    "KnownBlock",
+    "Message",
+    "MessageRole",
+    "ParseError",
+    "ParseResult",
+    "ProviderNotFoundError",
+    "RawSource",
+    "ReasoningBlock",
+    "TextBlock",
+    "UnknownBlock",
+]

convolvger-0.1.0/src/convolvger/core/archive.py

@@ -0,0 +1,106 @@
+"""The archival package produced by the JSON export.
+
+The Markdown renderer is a dissemination package and may omit content.
+This is the archival package: it omits nothing the canonical model holds.
+
+Extraction findings and the retrieval time describe the capture event
+rather than the conversation, so they sit beside the conversation here,
+matching ``ParseResult`` rather than contradicting it. ``conversation``
+alone round-trips back to an equal ``Conversation``.
+"""
+
+import json
+from datetime import datetime
+from importlib.metadata import PackageNotFoundError, version
+
+from pydantic import BaseModel, ConfigDict, Field, ValidationError
+
+from convolvger.core.errors import ConvolvgerError
+from convolvger.core.findings import Finding
+from convolvger.core.models import Conversation
+
+SCHEMA_VERSION = 2
+"""Bumped only when a change would stop an older reader loading a file.
+
+Version 2 replaced the ``warnings`` list of strings with ``findings``.
+Adding a field is safe for a reader that allows unknown ones; removing
+or renaming one is not.
+"""
+
+
+class ArchiveError(ConvolvgerError):
+    """Raised when a file cannot be read as an archive of this version.
+
+    Lives here rather than in ``errors`` for the same reason
+    ``ParseError`` lives beside the parser: it belongs to the format it
+    guards.
+    """
+
+
+def _tool_version() -> str:
+    try:
+        return version("convolvger")
+    except PackageNotFoundError:
+        return "unknown"
+
+
+class ArchiveEnvelope(BaseModel):
+    """A conversation together with the provenance of its capture.
+
+    ``extra="allow"``, unlike every other model here. An archive is a
+    permanent file that a later version of this tool must be able to
+    read: forbidding unknown fields would make every future addition a
+    breaking change, and ignoring them would drop them on
+    re-serialisation. Allowing them preserves a field this version does
+    not model. The canonical models keep ``forbid`` -- they guard an
+    internal invariant, not a file format.
+    """
+
+    model_config = ConfigDict(extra="allow")
+
+    schema_version: int = SCHEMA_VERSION
+    tool: str = "convolvger"
+    tool_version: str = Field(default_factory=_tool_version)
+    retrieved_at: datetime | None = None
+    findings: list[Finding] = Field(default_factory=list)
+    conversation: Conversation
+
+
+def load_archive(text: str) -> ArchiveEnvelope:
+    """Read an archive this version can vouch for, or refuse it.
+
+    The declared schema version is checked before anything else is
+    trusted, because the envelope alone will not refuse a file it cannot
+    truthfully represent. A version 1 archive validates quite happily:
+    its ``warnings`` list survives as an unknown field and ``findings``
+    defaults to empty, so a reader that skipped this check would
+    pronounce a file recording real damage entirely clean. Refusal is
+    the only honest answer for a format this version cannot read as its
+    own.
+
+    Nothing here touches the filesystem. The caller owns reading the
+    file, as it already owns writing one.
+    """
+    try:
+        payload = json.loads(text)
+    except json.JSONDecodeError as error:
+        raise ArchiveError(f"Not JSON: {error}") from error
+
+    if not isinstance(payload, dict):
+        raise ArchiveError(
+            f"Not an archive: expected an object, found {type(payload).__name__}"
+        )
+
+    declared = payload.get("schema_version")
+    if not isinstance(declared, int):
+        raise ArchiveError("Not an archive: no schema_version")
+    if declared != SCHEMA_VERSION:
+        raise ArchiveError(
+            f"Archive declares schema version {declared}; "
+            f"this version reads {SCHEMA_VERSION}"
+        )
+
+    try:
+        return ArchiveEnvelope.model_validate(payload)
+    except ValidationError as error:
+        raise ArchiveError(f"Archive is not a valid envelope: {error}") from error

convolvger-0.1.0/src/convolvger/core/errors.py

@@ -0,0 +1,6 @@
+class ConvolvgerError(Exception):
+    """Base class for all Convolvger errors."""
+
+
+class ProviderNotFoundError(ConvolvgerError):
+    """Raised when no provider can handle the requested source."""