astp-docs-server 0.1.0__tar.gz

astp_docs_server-0.1.0/.dockerignore

@@ -0,0 +1,17 @@
+.git
+.gitignore
+**/__pycache__/
+*.py[cod]
+.pytest_cache/
+tests/
+# ...except the freshness guard, which the Dockerfile's freshness stage runs (I6).
+!tests/test_vendor_freshness.py
+dist/
+build/
+*.egg-info/
+.venv/
+venv/
+Dockerfile
+.dockerignore
+# NOTE: do not exclude *.md — the vendored corpus (src/astp_docs_server/corpus/**)
+# is markdown and must ship in the image.

astp_docs_server-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,93 @@
+name: publish
+
+# Publishes astp-docs-server to PyPI through Trusted Publishing: no stored
+# token. PyPI trusts this workflow file in this repository, in the `pypi`
+# environment, and nothing else.
+#
+# Started by hand from main. The upload waits for the `pypi` environment's
+# required reviewers.
+#
+# This package depends on astp-docs, so astp-docs must already be on PyPI.
+#
+# The corpus-freshness gate is the point of this workflow. The server ships a
+# vendored snapshot of the protocol documents, and a stale snapshot is a fully
+# valid corpus: the server answers confidently out of superseded normative text
+# and nothing reports a problem. ASTP_REQUIRE_CORPUS_FRESHNESS=1 turns the
+# "no source checkout, skipping" case into a failure, so this job cannot pass
+# by not looking.
+
+on:
+  workflow_dispatch:
+    inputs:
+      protocol_ref:
+        description: "ref of scorched-earth-labs/astp to check the vendored corpus against"
+        required: false
+        default: main
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    if: github.ref == 'refs/heads/main'
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Check out the protocol repository
+        uses: actions/checkout@v4
+        with:
+          repository: scorched-earth-labs/astp
+          ref: ${{ inputs.protocol_ref || 'main' }}
+          path: .protocol
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - name: Install
+        run: pip install -e ".[mcp,web,dev]" build twine
+      - name: Full suite, with the vendored corpus checked against the protocol repo
+        env:
+          ASTP_REQUIRE_CORPUS_FRESHNESS: "1"
+          ASTP_PROTOCOL_DIR: ${{ github.workspace }}/.protocol
+        run: pytest -q tests/test_vendor_freshness.py
+      - name: Full suite
+        run: pytest -q
+      - name: Build
+        run: python -m build
+      - name: Check
+        run: |
+          twine check dist/*
+          version=$(python -c "import tomllib; print(tomllib.load(open('pyproject.toml','rb'))['project']['version'])")
+          whl=dist/astp_docs_server-"$version"-py3-none-any.whl
+          python -c "import zipfile,sys; n=zipfile.ZipFile(sys.argv[1]).namelist(); sys.exit(not all(any(x.endswith('dist-info/licenses/'+f) for x in n) for f in ('LICENSE.txt','NOTICE')))" "$whl" \
+            || { echo "::error::the wheel does not carry LICENSE.txt and NOTICE"; exit 1; }
+          python -c "import zipfile,sys; n=zipfile.ZipFile(sys.argv[1]).namelist(); sys.exit(not any(x.endswith('corpus/open/vendor_manifest.json') for x in n))" "$whl" \
+            || { echo "::error::the wheel does not carry the vendored corpus"; exit 1; }
+          python - "$whl" <<'PY'
+          import json, sys, zipfile
+          z = zipfile.ZipFile(sys.argv[1])
+          name = next(n for n in z.namelist() if n.endswith("corpus/open/vendor_manifest.json"))
+          m = json.loads(z.read(name))
+          print(f"corpus: SPEC {m['spec_version']} from {m['source_commit'][:12]}, {len(m['files'])} files")
+          PY
+          status=$(curl -s -o /dev/null -w '%{http_code}' "https://pypi.org/pypi/astp-docs-server/$version/json")
+          test "$status" = 404 \
+            || { echo "::error::astp-docs-server $version is already on PyPI (HTTP $status); bump the package version"; exit 1; }
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/project/astp-docs-server/
+    permissions:
+      id-token: write  # the OIDC token PyPI exchanges for a short-lived upload token
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@release/v1

astp_docs_server-0.1.0/.gitignore

@@ -0,0 +1,11 @@
+__pycache__/
+*.py[cod]
+.venv/
+*.egg-info/
+dist/
+build/
+.pytest_cache/
+.env
+# Built indexes / vendored corpora — regenerated from source docs.
+/index_cache/
+/corpora_cache/

astp_docs_server-0.1.0/.protocol/.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,18 @@
+---
+name: Reference implementation bug
+about: The astp package does something other than what SPEC.md requires
+labels: bug
+---
+
+<!-- Suspected vulnerability? Do not file it here. See SECURITY.md. -->
+
+**Package version and commit**
+
+**Python version**
+
+**What SPEC.md requires** (section)
+
+**What the package does instead**
+
+**Smallest reproduction**
+<!-- Inputs, and expected vs actual output. For hashes, give the digests. -->

astp_docs_server-0.1.0/.protocol/.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,5 @@
+blank_issues_enabled: true
+contact_links:
+  - name: Report a vulnerability
+    url: https://github.com/scorched-earth-labs/astp/security/advisories/new
+    about: Integrity flaws in the specification or the reference implementation. Please report privately — see SECURITY.md.

astp_docs_server-0.1.0/.protocol/.github/ISSUE_TEMPLATE/proposal.md

@@ -0,0 +1,16 @@
+---
+name: Proposal
+about: New protocol surface (MINOR) or a change to canonical form (MAJOR)
+labels: proposal
+---
+
+**Problem**
+<!-- What can't be expressed or verified today? -->
+
+**Proposed surface**
+
+**Kind of change**
+<!-- MINOR (existing conformant implementations stay conformant) or MAJOR. See VERSIONING.md. -->
+
+**What happens to records that already exist**
+<!-- Required for MAJOR: how records sealed under the current construction remain verifiable. -->

astp_docs_server-0.1.0/.protocol/.github/ISSUE_TEMPLATE/spec_issue.md

@@ -0,0 +1,18 @@
+---
+name: Specification issue
+about: A contradiction, ambiguity, gap, or error in SPEC.md or a companion document
+labels: spec
+---
+
+**Document and section**
+<!-- e.g. SPEC.md §5.6, CONFORMANCE-BFM.md BR-001 -->
+
+**SPEC version**
+<!-- the Version: field at the top of SPEC.md -->
+
+**What the text says**
+
+**Why that is a problem**
+<!-- What can two careful implementers do differently and both claim to conform? -->
+
+**Suggested resolution** (optional)

astp_docs_server-0.1.0/.protocol/.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,21 @@
+## What this changes
+
+
+## Kind of change
+
+<!-- See VERSIONING.md. Would an implementation that conforms today still conform, unmodified? -->
+
+- [ ] No protocol change (reference implementation, tests, tooling, non-normative docs)
+- [ ] PATCH — errata; no semantic change
+- [ ] MINOR — additive surface
+- [ ] MAJOR — canonical form (needs the amendment process in GOVERNANCE.md)
+
+SPEC.md sections touched:
+
+## Checklist
+
+- [ ] `pytest` passes, and any test file I touched passes on its own
+- [ ] Normative change: `SPEC.md` `Version:` and `CHANGELOG.md` updated together
+- [ ] New or changed term: `GLOSSARY.md` updated first
+- [ ] New hash-producing behaviour: a test with a fixed expected value
+- [ ] New `.py` files carry the Apache-2.0 header

astp_docs_server-0.1.0/.protocol/.github/workflows/publish.yml

@@ -0,0 +1,61 @@
+name: publish
+
+# Publishes the reference package `astp` to PyPI through Trusted Publishing:
+# no stored token. PyPI trusts this workflow file in this repository, in the
+# `pypi` environment, and nothing else.
+#
+# Started by hand from main. A package release carries no vMAJOR.MINOR.PATCH
+# tag (GOVERNANCE.md §Releases), so there is no tag to trigger on. The upload
+# waits for the `pypi` environment's required reviewer.
+
+on:
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    if: github.ref == 'refs/heads/main'
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - name: Install
+        run: pip install -e ".[neo4j,dev]" build twine
+      - name: Full suite
+        run: pytest -q
+      - name: Build
+        run: python -m build
+      - name: Check
+        run: |
+          twine check dist/*
+          version=$(python -c "import tomllib; print(tomllib.load(open('pyproject.toml','rb'))['project']['version'])")
+          test "$(python -c 'import astp; print(astp.__version__)')" = "$version" \
+            || { echo "::error::astp.__version__ does not match pyproject.toml ($version)"; exit 1; }
+          python -c "import zipfile,sys; n=zipfile.ZipFile(sys.argv[1]).namelist(); sys.exit(not any(x.endswith('dist-info/licenses/NOTICE') for x in n))" dist/astp-"$version"-py3-none-any.whl \
+            || { echo "::error::the wheel does not carry NOTICE"; exit 1; }
+          status=$(curl -s -o /dev/null -w '%{http_code}' "https://pypi.org/pypi/astp/$version/json")
+          test "$status" = 404 \
+            || { echo "::error::astp $version is already on PyPI (HTTP $status); bump the package version"; exit 1; }
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/project/astp/
+    permissions:
+      id-token: write  # the OIDC token PyPI exchanges for a short-lived upload token
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@release/v1

astp_docs_server-0.1.0/.protocol/.github/workflows/tests.yml

@@ -0,0 +1,69 @@
+name: tests
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+permissions:
+  contents: read
+
+jobs:
+  pytest:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.11", "3.12"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+          cache: pip
+      - name: Install
+        run: pip install -e ".[neo4j,dev]"
+      - name: Full suite
+        run: pytest -q
+      - name: Each test file on its own
+        # A file that only passes because another file ran first is a broken file.
+        run: |
+          status=0
+          for f in $(git ls-files 'tests/**/test_*.py'); do
+            env -u ARIADNE_ENABLED pytest -q "$f" || { echo "::error file=$f::fails when run alone"; status=1; }
+          done
+          exit $status
+
+  package:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - run: pip install build twine
+      - run: python -m build
+      - run: twine check dist/*
+
+  dco:
+    # CONTRIBUTING.md, "Certificate of origin": every commit carries its author's sign-off.
+    if: github.event_name == 'pull_request'
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+      - name: Every commit is signed off by its author
+        env:
+          BASE: ${{ github.event.pull_request.base.sha }}
+          HEAD: ${{ github.event.pull_request.head.sha }}
+        run: |
+          status=0
+          for c in $(git rev-list --no-merges "$BASE..$HEAD"); do
+            want="Signed-off-by: $(git log -1 --format='%an <%ae>' "$c")"
+            if ! git log -1 --format='%(trailers:key=Signed-off-by,unfold)' "$c" | grep -qxF "$want"; then
+              echo "::error::$(git log -1 --format='%h %s' "$c") lacks '$want'"
+              status=1
+            fi
+          done
+          exit $status

astp_docs_server-0.1.0/.protocol/.gitignore

@@ -0,0 +1,13 @@
+__pycache__/
+*.py[cod]
+*$py.class
+*.egg-info/
+dist/
+build/
+.eggs/
+*.egg
+.pytest_cache/
+.venv/
+venv/
+.env
+astp.code-workspace

astp_docs_server-0.1.0/.protocol/.mailmap

@@ -0,0 +1,10 @@
+# Map build-machine and personal identities to their project identities.
+#
+# This file changes only what git DISPLAYS. It rewrites no commit, changes no
+# SHA, and therefore leaves intact the commit identifiers cited in the
+# ratification records under docs/ and in SPEC.md.
+#
+# Format: Proper Name <proper@email> Commit Name <commit@email>
+
+Scorched Earth Labs <dev@scorchedearthlabs.com> selserver <selserver@og-ca-app01-sel-local.tail24b730.ts.net>
+Mick Smothers <mick.smothers@scorchedearthlabs.com> Mick Smothers <mick.smothers@gmail.com>

astp_docs_server-0.1.0/.protocol/AGENTS.md

@@ -0,0 +1,64 @@
+# AGENTS.md
+
+Guidance for AI coding agents (Claude Code, Codex, Copilot, Cursor and others) working in this repository. Human contributors: start with [`CONTRIBUTING.md`](./CONTRIBUTING.md).
+
+## What this repository is
+
+ASTP is a **protocol** — a specification plus a reference implementation — not an application. It ships:
+
+1. The normative specification, `SPEC.md`, with its companion documents: `CONFORMANCE*.md` (conformance requirements), `IMPLEMENTATION-*.md` (implementer guides), `GLOSSARY.md`, `VERSIONING.md`, `CHANGELOG.md`.
+2. The Python package `astp/` — protocol primitives, node types, the two adapter contracts and their in-memory reference implementation. No storage provider is named anywhere in it.
+3. The test suite under `tests/`.
+
+`docs/history/` holds superseded documents, kept for provenance. Do not implement from them and do not update them.
+
+## Commands
+
+```bash
+pip install -e ".[dev]"           # editable install with test dependencies
+pytest                            # full suite; needs no database and no network
+pytest tests/unit/protocol/test_verification.py
+pytest tests/unit/protocol/test_verification.py::test_name -v
+```
+
+There is no lint, format, or typecheck command configured. Don't invent one. Every test file must pass on its own as well as in the full run.
+
+The suite needs no database and no network: the operations run against `astp.adapters.memory.InMemoryStore`. A deployment's adapter, and its integration tests, live with that deployment.
+
+## Architecture
+
+```
+astp/protocol/   Node-generic layer. Operates on CognitiveNode only.
+astp/nodes/      Node-type instantiation (episode/, segment/). Each defines its NodePayload.
+astp/core/       Episode-era schema, governance, WIL, branching, grouping,
+                 cross-episode linking, workflow_execution (Layer 3), seal_v2
+                 (5.0.0 seal constructions), context_v1 and context_operations
+                 (6.0.0 context commitment: constructions, and the operations over StructuralStore).
+astp/adapters/   ASTPAdapter + StructuralStore contracts; InMemoryStore implements both.
+```
+
+**The namespace firewall is the most important invariant in the tree:** nothing under `astp/protocol/` imports from `astp/nodes/`. `tests/unit/protocol/test_namespace_firewall.py` enforces it, along with a second rule: `astp/protocol/` imports nothing from `astp/core/` or `astp/adapters/` either. If a change seems to need such an import, the symbol is in the wrong layer — move the symbol or rethink the design. Do not relax the test.
+
+### Persistence layers (SPEC §3.4 — not the same thing as the directories above)
+
+- **Layer 1 — Merkle Spine.** The hash-chained, authoritative cognitive record.
+- **Layer 2 — Episode Content.** Segments and their supporting structures, anchored to Layer 1 by parent reference.
+- **Layer 3 — Workflow & Execution DAG** (SPEC §21; `astp/core/workflow_execution.py`). Cryptographically isolated: it references Layers 1 and 2 by identifier only and is never hash-linked into the Spine. Each Layer 3 node type has one designated writer per workspace (the Cognitive Implementation Authority). Do not add multi-writer paths.
+
+## Invariants that are not obvious from local context
+
+- **Dual index.** `sequence_index` (immutable temporal position) is in the leaf hash preimage. `tree_leaf_index` (mutable structural position) is not. Never swap them. See `astp/protocol/leaf_hash.py`.
+- **Canonical form is stable within a major version.** A change to any hash preimage, Merkle construction, canonical serialization, or required field is a MAJOR protocol change under `VERSIONING.md` and goes through the amendment process in `GOVERNANCE.md`. It is never a quiet code change, and it is always introduced as a new versioned construction so existing sealed records stay verifiable.
+- **Wire constants kept the `ariadne` prefix when the package became `astp`.** HKDF `info` strings, the `ariadne::` coordinator key prefix, `Ariadne*` graph labels. They feed derived keys or name stored data. `tests/unit/protocol/test_wire_constants.py` pins them; do not "fix" them.
+- **Governance rules (`G-*`, numbered in `SPEC.md`)** are enforced where the write happens and raise. Do not catch and continue; adapters must surface the violation.
+- **Reparenting is forbidden.** `parent_node_id` is in the leaf hash. To correct parentage, create a new node and deprecate the old one.
+- **Sealed nodes are immutable.** Corrections go forward: new node plus a deprecation or succession edge. There is no in-place edit path.
+- **Crystallization is a state transition, not a receipt.** `CrystallizationDelta` is immutable after creation.
+- **WIL write ordering** (`astp/core/wil.py`, SPEC §12): durable content store → authoritative structural store → ephemeral coordinator → search index. Every write is idempotent, and an interruption at any phase is recoverable.
+
+## Documents
+
+- `SPEC.md`'s `Version:` field **is** the protocol version. A normative change updates that field and `CHANGELOG.md` together; a test checks they agree. `astp.PROTOCOL_VERSION` names the SPEC version the package implements; `astp.__version__` is the package's own version.
+- `GLOSSARY.md` is the single source for definitions. Reference it; if you introduce a term, add it there first.
+- New normative or companion documents carry the header block the existing ones use: **Version**, **Status**, **Authors**, **Date**.
+- New `.py` files start with the repository's Apache-2.0 header, before the module docstring.