For Coding Agents¶

Reference for AI agents that work on iscc-hub or call a hub. Tables and rules first. The code is the source of truth; the IEPs define the protocol.

Architecture map¶

Django 6.1 + django-ninja, Python 3.12+. One process type: Gunicorn sync workers. SQLite (WAL) by default, PostgreSQL optional.

Request flow for POST /declaration: middleware → api.declaration → validators.validate_iscc_note → permission check (PubKey) → identity (DID verification) → sequencer.sequence_iscc_note → 201 {iscc_id, seq}.

Decision dispatch¶

Constraints and invariants¶

Load-bearing (never change without discussion): entry bundle framing, log entry envelope, checkpoint format, RFC 6962 hashing and height-8 tiles, /log/ paths, ISCC-ID encoding, signature scope and JCS.

Side effects¶

Task recipes¶

uv sync                                   # install
uv run poe all                            # format, lint, types, tests (100% coverage required)
uv run pytest tests/test_x.py --no-cov    # one test file
uv run pytest -m slow                     # slow tests (Go conformance, fuzzing)
uv run poe build-schema                   # regenerate schema.py from openapi.yaml
uv run poe docs-build && uv run poe docs-check   # build and check this site

Tests that touch the sequencer or the API use @pytest.mark.django_db(transaction=True). Without transaction=True, pytest-django wraps the test in a transaction and BEGIN IMMEDIATE fails.

Sign a note in a client:

import iscc_crypto as icr

key = icr.key_from_secret(secret, controller="did:web:example.com")
note = {
    "$schema": "http://purl.org/iscc/schema/iscc-note-0.8.0.json",
    "iscc_code": code,
    "datahash": datahash,
    "nonce": icr.create_nonce(hub_id),
    "units": units,
}
signed = icr.sign_json(note, key)  # POST as JSON to /declaration

A full, tested client example is on Use the API.

Change playbook¶

Common mistakes¶

NEVER edit iscc_hub/schema.py. ALWAYS change openapi.yaml and run uv run poe build-schema.

NEVER call obj.save() on an IsccDeclaration from code that can run during a deletion. A stale save inserts the row again. ALWAYS use filter(pk=...).update(...).

NEVER use @pytest.mark.django_db without transaction=True for sequencer or API tests.

NEVER write tests with mocks for crypto. ALWAYS use real Ed25519 keys and the fixtures in tests/conftest.py.

NEVER treat specs/ as authoritative. ALWAYS check the IEPs and the code.

NEVER send a resolve request without Accept: application/json if you want JSON. Without it, GET /{iscc_id} returns HTML or a redirect.