fuaran-py 0.0.1__tar.gz

fuaran_py-0.0.1/.gitattributes

@@ -0,0 +1,31 @@
+# Pin canonical text-file line endings to LF.
+#
+# `text=auto` lets git detect text vs. binary; `eol=lf` pins the
+# canonical in-repo line ending. On a Windows checkout, files stay LF
+# on disk (no autocrlf round-trip churn), eliminating the recurring
+# "LF will be replaced by CRLF the next time Git touches it" warnings
+# and phantom "modified" churn on tool-regenerated files.
+
+* text=auto eol=lf
+
+# Explicit binary types — git's auto-detection is usually correct
+# but spell out the common ones to be safe.
+*.png   binary
+*.jpg   binary
+*.jpeg  binary
+*.gif   binary
+*.ico   binary
+*.svg   binary
+*.dll   binary
+*.exe   binary
+*.pdb   binary
+*.nupkg binary
+*.snupkg binary
+*.zip   binary
+*.tar   binary
+*.gz    binary
+*.pdf   binary
+*.woff  binary
+*.woff2 binary
+*.ttf   binary
+*.eot   binary

fuaran_py-0.0.1/.github/workflows/ci.yml

@@ -0,0 +1,150 @@
+# Build, test and wire-format conformance gate for the Python host.
+#
+# ── Layout ───────────────────────────────────────────────────────────────────
+# The conformance corpus is its own public repository. The test suite resolves
+# it as a SIBLING of this repo root (tests/_corpus.py walks to
+# `<container>/wire-format-fixtures`), so this repo is checked out into a
+# subdirectory and the corpus beside it:
+#
+#     $GITHUB_WORKSPACE/
+#     ├── fuaran-py/               ← this repo
+#     └── wire-format-fixtures/    ← the corpus (fuaran-ui/fuaran-ui-specification)
+#
+# The corpus repository is PUBLIC, so the checkout is anonymous — no token.
+#
+# ── Why the corpus assertion below is not optional ───────────────────────────
+# When the corpus is absent, tests/_corpus.py does NOT fail — it silently falls
+# back to the committed offline snapshot under conformance/corpus/. A layout
+# drift would therefore leave the suite certifying against a stale local copy of
+# the spec while the job stayed green, which is the one failure mode a
+# conformance gate must never have. The assertion turns that into a hard stop.
+
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+permissions:
+  contents: read
+
+env:
+  # ── QUARANTINE ──────────────────────────────────────────────────────────────────────────
+  # Cases that fail on a clean tree are excluded from the blocking gate here, so
+  # that a NEW regression is caught while known drift stays visible. An entry is
+  # not a judgement that a case is wrong — it is a record of known, understood,
+  # outstanding work, and the list SHRINKS TO EMPTY as the decoder catches up.
+  # Delete entries as they start passing; do not add to it to make a red build
+  # green without a root-cause note — a new failure here is the regression this
+  # gate exists to catch.
+  #
+  # EMPTY as of 2026-08-13: the Toggle/Now/Switch vocabulary landed
+  # (3ac3c87/8e9fac3), the offline corpus snapshot was re-synced (392abd6), and
+  # every formerly quarantined case passes against the current corpus —
+  # verified by the full suite at 1627 passed with zero deselections AND each
+  # former entry re-run by node ID (24 passed). The machinery stays armed; a
+  # future corpus advance repopulates the list the same way.
+  QUARANTINE: ""
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    defaults:
+      run:
+        working-directory: fuaran-py
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          path: fuaran-py
+
+      # Deliberately UNPINNED: the corpus is the shared conformance authority
+      # every host certifies against, and one current spec for all hosts is the
+      # point of giving it a single home. Pinning here would let this host drift
+      # from the spec without anything going red.
+      - name: Check out the wire-format conformance corpus
+        uses: actions/checkout@v4
+        with:
+          repository: fuaran-ui/fuaran-ui-specification
+          path: wire-format-fixtures
+
+      - name: Assert the corpus is where the tests resolve it
+        run: test -f ../wire-format-fixtures/manifest.json
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.13'
+
+      - name: Install
+        run: |
+          python -m pip install --upgrade pip
+          python -m pip install ".[dev]"
+
+      - name: Lint (ruff check)
+        run: python -m ruff check .
+
+      - name: Format check (ruff format)
+        run: python -m ruff format --check .
+
+      - name: Type check (mypy)
+        run: python -m mypy
+
+      # Print what this gate does NOT cover, on every run. A cap nobody can see
+      # reads as "covered everything".
+      - name: Report the conformance quarantine
+        run: |
+          if [ -n "$QUARANTINE" ]; then
+            echo "The blocking gate below EXCLUDES these known-failing cases:"
+            echo "$QUARANTINE" | tr ' ' '\n' | grep -v '^--deselect$' | sed 's/^/  - /'
+          else
+            echo "Quarantine EMPTY — the blocking gate covers the full conformance suite."
+          fi
+          echo
+          echo "ALSO NOT GATED HERE — inert rather than quarantined (see the skip"
+          echo "summary that -rs prints under each test run below):"
+          echo "  - the reference-renderer parity tests read the reference host's source"
+          echo "    from a sibling checkout this workflow does not make, so they skip."
+          echo "    A skip here does NOT mean the path they look in is right: it was"
+          echo "    wrong for months (the host was renamed) and this note read as the"
+          echo "    explanation. What proves the path now is"
+          echo "    test_reference_host_resolves_in_a_cross_host_checkout, which never"
+          echo "    skips and fails in any checkout that HAS sibling hosts but no"
+          echo "    reference host. It passes here because this job is genuinely a"
+          echo "    single-host checkout — the one shape in which skipping is honest."
+          echo "  - the FastAPI sample-host tests skip because fastapi is a sample-only"
+          echo "    dependency and is not in the [dev] extra this job installs."
+          {
+            echo "### Conformance quarantine (excluded from the blocking gate)"
+            echo
+            if [ -n "$QUARANTINE" ]; then
+              echo '```'
+              echo "$QUARANTINE" | tr ' ' '\n' | grep -v '^--deselect$'
+              echo '```'
+            else
+              echo "Empty — the blocking gate covers the full conformance suite."
+            fi
+          } >> "$GITHUB_STEP_SUMMARY"
+
+      # Non-blocking: runs the FULL suite so the size of the existing drift is
+      # measured on every run rather than inferred from the quarantine list.
+      - name: Conformance drift (reported, non-blocking)
+        continue-on-error: true
+        run: |
+          set +e
+          python -m pytest -q -rs > drift.log 2>&1
+          status=$?
+          tail -40 drift.log
+          {
+            echo "### Full suite, including quarantined cases (non-blocking)"
+            echo
+            echo '```'
+            grep -E '^[0-9]+ (failed|passed)|failed,|passed,' drift.log | tail -3
+            echo '```'
+          } >> "$GITHUB_STEP_SUMMARY"
+          exit 0
+
+      # THE GATE. Everything the suite currently passes, including every
+      # conformance case outside the quarantine above.
+      - name: Test (gated)
+        run: python -m pytest -q -rs $QUARANTINE

fuaran_py-0.0.1/.github/workflows/publish-pypi.yml

@@ -0,0 +1,64 @@
+# Publish fuaran-py to PyPI on a version tag, via PyPI Trusted Publishing (OIDC — no stored token).
+#
+# Trigger: a `v*` tag push only. A branch push reaches no publish job.
+# Prerequisites (one-time, on pypi.org): register this repository as the project's trusted
+# publisher — owner `fuaran-ui`, repository `fuaran-py`, workflow `publish-pypi.yml`,
+# environment `pypi` — then create the `pypi` environment on this repository.
+# The tag must equal the version in pyproject.toml; the gate below refuses otherwise, so a
+# mistyped tag never publishes a mismatched release.
+name: publish-pypi
+
+on:
+  push:
+    tags: ["v*"]
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.13"
+      - name: Version gate — tag must equal pyproject version
+        run: |
+          set -euo pipefail
+          tag="${GITHUB_REF_NAME#v}"
+          ver="$(python - <<'PY'
+          import tomllib
+          print(tomllib.load(open("pyproject.toml","rb"))["project"]["version"])
+          PY
+          )"
+          if [ "$tag" != "$ver" ]; then
+            echo "tag v$tag does not match pyproject version $ver" >&2
+            exit 1
+          fi
+      - name: Build sdist + wheel
+        run: |
+          python -m pip install --upgrade pip build
+          python -m build
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+          if-no-files-found: error
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write
+      contents: read
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - name: Publish to PyPI (Trusted Publishing)
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          skip-existing: true

fuaran_py-0.0.1/.gitignore

@@ -0,0 +1,32 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+.eggs/
+build/
+dist/
+
+# Virtual environments
+.venv/
+venv/
+env/
+
+# Tooling caches
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.coverage
+htmlcov/
+coverage.xml
+
+# Editors / OS
+.vscode/
+.idea/
+.DS_Store
+Thumbs.db
+
+# The synced corpus snapshot (conformance/corpus/) IS committed — it makes
+# fuaran-py standalone-testable offline and gives the drift guard
+# (tests/test_corpus_sync.py) a committed baseline to pin against the authority.
+# Re-sync + re-commit it whenever the authoritative corpus regenerates
+# (python conformance/sync_corpus.py), per the §11 forward-coupling rule.

fuaran_py-0.0.1/CLAUDE.md

@@ -0,0 +1,307 @@
+# CLAUDE.md — fuaran-py (Python reference implementation)
+
+This repo is the **Python host of the Fuaran UI language** — a **co-equal sibling
+to the F# (`Fuaran.UI`) and TypeScript (`@fuaran-ui/*`) tiers**, not merely a
+codec. The target identity is a full authoring + rendering host: an ergonomic
+`fuaran_py.ui` smart-constructor authoring surface (roadmap Phase 278), a tree-op
+apply engine (279), a server-HTML renderer (`fuaran_py.renderer`, Phase 239 —
+shipped) plus an interactive Pyodide client runtime (280), all conformant to the
+shared wire format. What ships **today** is the floor: the canonical-JSON codec
+(`decode_node` / `encode_node` / `decode_op` / `encode_op`), a pre-emit validator,
+the corpus conformance harness, and the headless renderer; the authoring +
+interactive surfaces are the Wave 35 co-equality expansion (Phases 278–281).
+
+**Framing — load-bearing, do not regress.** The LLM's emission surface is the
+**canonical JSON wire format, for every host**. The three language tiers (F#, TS,
+Python) are **human-developer authoring surfaces** that produce that JSON; the AI
+never authors host-language code — a structure-free baseline exists only as the
+*thing to beat*, not a direction. Python being
+the language AI orchestrators are written in is a reason it is *valuable*, not a
+reason to make it a lesser, codec-only kind of artefact than F#/TS.
+
+This repo sits alongside the `fuaran` (F#) and `fuaran-ts` (TypeScript) tiers as a co-equal
+conformant host. Cross-repo development conventions (port allocation, formatting, language-baseline pinning) live at the maintainers' workspace level and are not shipped here.
+
+## Posture
+
+- **Apache 2.0 from day one** — same posture as `fuaran-ts`, to make the
+  reference-implementation claim unambiguous.
+- **Sibling reference implementation, not a transpile.** `fuaran-py` is built to
+  the language-neutral wire-format spec (`../fuaran-dotnet/docs/WIRE_FORMAT.md`) +
+  conformance corpus (`../wire-format-fixtures/`), not generated from the F# tier.
+  The Fable-Python build-vs-port evaluation that settled this is recorded in
+  [`docs/fable-python-decision.md`](docs/fable-python-decision.md).
+- **Wire-format conformance is the stability contract.** The codec encodes /
+  decodes byte-identically against the shared corpus; it is certified the same
+  way the F# and TypeScript hosts are.
+- **Dependency-light.** The runtime codec uses only the Python standard library.
+  Third-party packages appear only as dev tooling (`pytest` / `mypy` / `ruff`).
+
+## Language baseline
+
+CPython **3.13+** (the workspace-chosen floor for this sibling; uses PEP 695
+type parameters / `type` aliases). The Python analogue of the workspace's
+F#-10/.NET-10 pinning.
+
+## Layout
+
+```
+fuaran-py/
+├── src/fuaran_py/
+│   ├── canonical.py      # the canonical-JSON encoder (number form, key sort, escaping)
+│   ├── model.py          # the structural typed tree (Node / Obj / Arr)
+│   ├── result.py         # Ok / Err + the six DecodeError codes
+│   ├── schema/           # decode_node / encode_node + the per-kind field schemas
+│   ├── ops/              # decode_op / encode_op over the 11-op TreeOp algebra
+│   ├── op_stream/        # hash-chained provenance log: StreamEntry envelope + SHA-256 chain + in-memory sink + replay
+│   ├── validator/        # pre-emit, default-deny-by-shape structural validator
+│   ├── ai_tools/         # AI-tools introspection: emittable-surface catalog + value-space + tool schemas + tree introspection + default-deny dispatch gate (Phase 237)
+│   ├── conformance/      # corpus round-trip smoke harness + certification bridge + the cross-host fuzz-sample exchange (Phase 236)
+│   ├── renderer/         # optional server-HTML renderer + sanitiser + reference CSS (Phase 239)
+│   ├── style_observer/   # computed-style observer: pure flag tier + InMemory + Pyodide live read-back
+│   └── theme_manifest/   # DTCG-compatible theme contract (tokens + role bindings + invariants)
+├── tests/                # pytest: number form, full-corpus round-trip + reject, validator
+├── docs/                 # fable-python-decision.md (the build-vs-port decision record)
+├── pyproject.toml        # dependency-light; dev extras = pytest / mypy / ruff
+├── LICENSE               # Apache 2.0 + Diametrical Ltd copyright
+└── run.ps1               # Stage-0 entry point — lint + format-check + type-check + test
+```
+
+## Build / verify pipeline
+
+```powershell
+.\run.ps1                 # provision .venv (first run) + ruff + mypy + pytest
+.\run.ps1 -SkipInstall    # run the gate against an already-provisioned .venv
+```
+
+Or drive the tools directly inside the venv: `ruff check .`, `ruff format .`,
+`mypy`, `pytest`.
+
+## Formatting mandate
+
+The workspace formatting mandate (Fantomas for F#, Prettier for TS) maps here to
+**ruff** — every commit is preceded by `ruff format` + `ruff check` over the
+changed files. The CI gate is `ruff format --check` + `ruff check`.
+
+## Wire format
+
+The canonical wire format is owned by the F# `fuaran` tier
+(`../fuaran-dotnet/docs/WIRE_FORMAT.md`) with the workspace-level
+`../wire-format-fixtures/` corpus as the executable conformance suite. `fuaran-py`
+is one conformant host: it round-trips the corpus byte-for-byte and surfaces the
+canonical reject code + path for every malformed fixture. The **forward-coupling
+rule** (`WIRE_FORMAT.md` §11) means a new `NodeKind` / `Spec` / `TreeOp` /
+`Binding` / `Action` case must move every host in one change — `fuaran-py` is now
+one of those hosts.
+
+### Conformance coverage (v0 bootstrap)
+
+The codec **runs the full four-family corpus green** — node round-trips, op
+round-trips, rejects, and `lenient-accept` per WIRE_FORMAT §16's normative
+block (fixture counts drift as the corpus grows —
+`../wire-format-fixtures/manifest.json` is the authoritative enumeration).
+The 2026-07-05 parity pass closed the measured divergences: the `Mount`
+NodeKind decodes (typed scopeId/channel, structural inputs); the §16
+bare-string TextSource shorthand is accepted and normalises to canonical
+bytes; JSON null rejects in structured JVal positions at the null's exact
+path (`_from_json_strict` — the §5 `Binding.Static` opaque seam deliberately
+stays null-lenient); the op decoder gates the reserved `"<opaque>"` /
+`"<closure>"` sentinels in `UpdateProp` values like the F# reference. Typed
+field-level validation is implemented for the common kinds;
+recognised-but-not-yet-typed kinds are accepted structurally (still
+byte-exact on round-trip). The formal certification harness (offline corpus
+snapshot + drift guard, schema validation, a language-agnostic certification
+bridge, a CI leg, and generative parity) has since landed.
+
+### Within-host parity vs the cross-host exchange (do not conflate these)
+
+Two generative floors sit above the curated corpus, and each proves something the
+other cannot:
+
+- **Within-host** — `tests/test_generative_parity.py`, ≥1000 `hypothesis` trees,
+  `encode(decode(encode x)) == encode x`. This host's canonical form is a fixed
+  point. Self-consistency only: a misreading of the spec that this host applies
+  *consistently* passes it every time.
+- **Cross-host** — `fuaran_py.conformance.fuzz_exchange`, the fuzz-sample
+  exchange. Another host emits its canonical bytes for generated trees into
+  `<dir>/fsharp/`; this module decodes + re-encodes each through the Python codec,
+  asserts byte-identity, and writes **this** host's canonical output to
+  `<dir>/python/` so the sibling's `--check-fuzz-samples <dir> python` can check
+  the converse direction. One host's output, a different host's codec — the only
+  arrangement in which a shared misreading is visible.
+
+The exchange needs a sibling host's emitter and so is hand-driven (the module
+docstring carries the full command sequence); the within-host floor runs under a
+plain `pytest`. `tests/test_fuzz_exchange.py` pins the *runner* — that it detects
+a divergence, emits this host's set, and refuses a missing input set — using real
+corpus payloads, so it needs no other toolchain.
+
+The exchange's directory names (`fsharp` / `python`) are a cross-repo contract
+with the sibling's `--check-fuzz-samples <dir> <host>` argument; renaming either
+side silently un-wires it.
+
+### Decoder robustness fuzz (`fuaran_py.conformance.decoder_fuzz` + `tests/test_decoder_fuzz.py`)
+
+A third generative floor, and the only one aimed at inputs a conformant emitter would never produce.
+The refusal contract — decoding is TOTAL, so a malformed or hostile input yields a structured typed
+error, never an exception and never a hang — is asserted against **generated** hostile input rather
+than against the curated reject corpus alone. A curated corpus is evidence about the author's
+imagination.
+
+- **The bounded run IS the PR gate.** It landed in the suite `pytest` already runs, so no workflow
+  change was needed and none can silently switch it off.
+- **The long run is a CLI**, and it writes its own machine-readable record:
+  `python -m fuaran_py.conformance.decoder_fuzz --long --iterations 250000 --evidence <file>`.
+- **The go-red self-test is permanent, and so is its inverse.** Five mutants, one per invariant, plus
+  a pin that each is PARTIAL — a mutant that broke every input would make the harness look sensitive
+  while testing nothing.
+- **The allocation invariant is split in two, deliberately.** The main stream carries a cheap
+  canonical-output amplification proxy; `test_pathological_inputs_stay_inside_an_allocation_budget`
+  spends `tracemalloc` on the pathological family, where an adversarial shape would actually
+  amplify. Neither half is the whole invariant, and the docstrings say which is which.
+- **`RecursionError` is the escape this host most needs to see.** A recursive-descent decoder that
+  lets the interpreter's stack limit answer for it has no depth guard, whatever its §21 constant
+  says. `check` catches it and reports it as a counterexample rather than letting it propagate.
+- **The generator is a SIBLING of the reference one, not a transpile.** Same five input families; a
+  different byte stream, necessarily — the reference alphabet carries lone surrogates a `str` cannot
+  encode to UTF-8 at all, and the module names that gap rather than closing it silently.
+- **The `duplicate-key` mutator and the `NaN` / `Infinity` / `1e999` / `+1` tokens are generated
+  deliberately, and nothing here asserts which answer is right.** Those are §20 "Decode
+  determinism", landed PROPOSED and not yet ratified; crash-freedom on them is in scope, agreement
+  is not.
+
+`fuaran_py.conformance.refusal_report` is the companion emitter: this host's refusal class for every
+reject fixture, as JSON, for a cross-host runner that compares the hosts to each other rather than
+each to the corpus in isolation.
+
+## Renderer (Phase 239)
+
+`fuaran_py.renderer.render_html` walks a decoded `Node` tree and emits a
+**body-fragment HTML string** carrying the reference `fuaran-*` class vocabulary,
+so the byte-copied stylesheet styles it exactly as the F#/TS hosts style their
+output. Server semantics mirror the F# SSR precedent: no runtime, no dispatch
+(`Button` inert, `Link` a real `<a href>`), `Static` bindings resolve and the
+rest placeholder to an em-dash, and a visualisation this host cannot paint
+renders a deterministic placeholder. A **data-bound `DataGrid` renders its
+rows** — the completeness posture; the declared boundary (a closure-projected
+column, which cannot survive the wire) is written up in the README's
+"Bound-grid rendering" section.
+
+Two disciplines keep it honest:
+
+- **Reference-CSS byte-copy.** `src/fuaran_py/renderer/content/fuaran-reference.css`
+  is a byte-for-byte copy of the F# canonical
+  (`../fuaran-dotnet/src/Fuaran.UI.Renderer/content/fuaran-reference.css`). A test
+  (`test_render_parity` / the byte-identical check) fails if the copy drifts when
+  the F# sibling is checked out alongside. Re-copy it in the same change-set as
+  any F#-side CSS change (the §11 forward-coupling rule now spans this host too).
+- **Class-name vocabulary parity.** `tests/test_render_parity.py` extracts the
+  class vocabulary straight from the F# reference renderer source (`Render.fs` +
+  `Theme.fs`, literals + `sprintf "...-%s"` prefixes) and asserts every class the
+  Python renderer emits over the node corpus is in it — a cross-host parity lock,
+  the rendering analogue of the wire corpus. It skips when the F# sibling is
+  absent. **A new `NodeKind` / variant that changes the emitted class vocabulary
+  updates the renderer here in the same move that updates the codec.**
+
+Sanitisation matches the F#/TS posture (`fuaran_py.renderer.sanitize` ports
+`Sanitize.fs`): URL-scheme default-deny, `data-*`/`aria-*` attribute allowlist,
+markdown escaped-first then swept. The `Custom` host-renderer registry is a host
+trust boundary — the baseline ships no registry seam, so `Custom` renders an
+inert labelled placeholder.
+
+**Destination policy is AMBIENT on the render context, and defaults to deny.**
+`Renderer.egress_policy` (`fuaran_py.renderer.egress`, the port of the reference
+host's destination-policy section) is consulted by every `href` / `src` the
+renderer emits — the `Link` node's `href` under the `HYPERLINK` class, the
+`Image` node's `src` under `MEDIA`, and the whole markdown body through
+`markdown.to_html_with_egress`. `render_html(..., egress_policy=…)` and
+`FuaranRuntime(..., egress_policy=…)` are the declaration points; both default to
+`DENY_NON_LOCAL_EGRESS`, so a host that declares nothing gets deny, and
+`PERMISSIVE_EGRESS` is reachable only by that name.
+
+Three disciplines follow, and the third is the one that decays quietly:
+
+- **A new emission that carries a URL owes a policy consultation in the same
+  change.** `sanitize_url_or_blank` is the *floor*, not the seam — reaching for
+  it directly at a render call site re-opens the hole the ambient default closed.
+  Use `egress.sanitize_url_for_egress(self.egress_policy, <class>, url)` and
+  splice the returned attribute pairs onto the emitted element, last.
+- **Never widen the default to make a test pass.** The corpus fixtures and the
+  ambient tests in `tests/test_egress_policy.py` are the falsifiers in both
+  directions; a fixture that needs an off-origin host names a policy.
+- **`tests/test_markdown_corpus.py` runs TWO legs.** The seam leg calls
+  `to_html_with_egress` directly; the ambient leg renders a `Markdown` node
+  through `render_html` with **no policy named** for the `denyNonLocal` fixtures.
+  Keep both — the seam leg cannot detect a renderer that stopped reaching the
+  seam, which is precisely the state this host was in while the policy was merely
+  available.
+
+The README's "Destination policy" section carries the host-facing contract and
+the four declared shape differences from the reference host.
+
+## Op-stream (hash chain)
+
+`fuaran_py.op_stream` is the Python host of the op-stream **hash-chained provenance
+log** — the twin of the F# and TypeScript op-stream tiers. A stream's applied
+`TreeOp` edits are an append-only sequence of `OpRecord` envelopes; a host-side
+SHA-256 chain (`sha256(previousHash | payload)`) links them so the stream is
+tamper-evident. The pre-image is byte-identical across hosts: the versioned
+`StreamEntry` envelope leads with `{"v":2,…}` (the chain format version folded in
+first), wrapped in the canonical delimited `{"seq":…,"actor":…,"op":…}` payload,
+with the op encoded by the shared `fuaran_py.ops.encode_op` + `fuaran_py.canonical`
+(never a re-implemented encoder). The module is **stdlib-only** — unlike the
+Fable-constrained hosts it uses `hashlib.sha256` directly.
+
+- **Conformance is the contract.** `tests/test_op_stream.py` loads the shared
+  `chain/chain-corpus.json` golden and asserts every computed chain hash equals the
+  committed value byte-for-byte — the same corpus the F# and TypeScript hosts
+  certify against. A mismatch is a bug in this host's encoder/chain, **never** the
+  corpus; do not regenerate the golden to make a test pass.
+- **Version lock-step.** `CHAIN_FORMAT_VERSION` is pinned to the corpus `version`;
+  bump it in lock-step with the other hosts + the golden whenever the pre-image
+  formula, envelope shape, or hash function changes (the wire-format forward-coupling
+  rule now spans the chain envelope too).
+
+## Computed-style observer + theme manifest
+
+`fuaran_py.style_observer` is the Python twin of `Fuaran.UI.StyleObserver`: it
+reads back a rendered tree's resolved computed styles and derives a fixed
+vocabulary of resolved-style flags (contrast-below-AA, invisible-text,
+accent-indistinct, plus the four manifest-aware checks) the semantic-state channel
+is blind to — as small typed facts, deterministically. The flag + observation
+JSON encode is **byte-identical** to the F# and TypeScript hosts.
+
+- `InMemoryStyleObserver` — fixture-driven, substrate-free (tests / headless).
+- `BrowserStyleObserver` — reads **live** `getComputedStyle` under **Pyodide**
+  (CPython compiled to WASM running client-side in the browser — the Python
+  analogue of the F# Fable / TS browser observers). Browser-API access is behind
+  an injectable `BrowserDeps` (default: the `js` interop module, imported lazily so
+  the package stays stdlib-only at install time and importable under plain CPython;
+  tests inject a fake DOM). `connect()` wires a live `MutationObserver`
+  (Pyodide-only) so a theme toggle re-derives automatically.
+
+`fuaran_py.theme_manifest` is the Python twin of `Fuaran.UI.ThemeManifest`: a
+DTCG-compatible token model + semantic role bindings + quantified invariants
+(per-role contrast floors, 60-30-10 usage budgets, motion voice). It is the
+contract the observer's manifest-aware tier (`per_node_flags` /
+`verify_usage_budgets`) verifies resolved style against. Both modules are
+stdlib-only; the Pyodide-only `js` / `pyodide.ffi` imports are lazy and
+import-guarded (the `#if FABLE_COMPILER` analogue). Manifest JSON encode + the F#
+`ThemeBridge` (typed-`Theme` projector) are not yet ported (follow-up).
+
+## Cross-repo dependencies
+
+No upstream dependency on any other sibling. At test time it reads the
+workspace-relative corpus at `../wire-format-fixtures/` (skipped when absent, so
+the repo is standalone-testable). It produces a Python package, not a NuGet pack
+— the workspace `pack-all.ps1` treats it as a no-op.
+
+## Public vocabulary discipline
+
+`fuaran-py` is OSS-public (Apache 2.0). Per the workspace OSS publication
+boundary, **shipped artefacts** (source, README, package metadata) reference only
+"the Fuaran UI wire format" generically — never a private sibling/package name,
+commercial product names, or the strategic-command names. The specific banned
+list lives in the workspace OSS publication boundary doc, not here. This
+`CLAUDE.md` lives in the public repo, so it observes the same boundary — it names
+no private sibling, package, product, or command.

fuaran_py-0.0.1/CODE_OF_CONDUCT.md

@@ -0,0 +1,77 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+We as members, contributors, and leaders pledge to make participation in our
+community a harassment-free experience for everyone, regardless of age, body
+size, visible or invisible disability, ethnicity, sex characteristics, gender
+identity and expression, level of experience, education, socio-economic status,
+nationality, personal appearance, race, caste, color, religion, or sexual
+identity and orientation.
+
+We pledge to act and interact in ways that contribute to an open, welcoming,
+diverse, inclusive, and healthy community.
+
+## Our Standards
+
+Examples of behavior that contributes to a positive environment for our
+community include:
+
+- Demonstrating empathy and kindness toward other people
+- Being respectful of differing opinions, viewpoints, and experiences
+- Giving and gracefully accepting constructive feedback
+- Accepting responsibility and apologizing to those affected by our mistakes,
+  and learning from the experience
+- Focusing on what is best not just for us as individuals, but for the overall
+  community
+
+Examples of unacceptable behavior include:
+
+- The use of sexualized language or imagery, and sexual attention or advances
+  of any kind
+- Trolling, insulting or derogatory comments, and personal or political attacks
+- Public or private harassment
+- Publishing others' private information, such as a physical or email address,
+  without their explicit permission
+- Other conduct which could reasonably be considered inappropriate in a
+  professional setting
+
+## Enforcement Responsibilities
+
+Community leaders are responsible for clarifying and enforcing our standards of
+acceptable behavior and will take appropriate and fair corrective action in
+response to any behavior that they deem inappropriate, threatening, offensive,
+or harmful.
+
+Community leaders have the right and responsibility to remove, edit, or reject
+comments, commits, code, wiki edits, issues, and other contributions that are
+not aligned to this Code of Conduct, and will communicate reasons for
+moderation decisions when appropriate.
+
+## Scope
+
+This Code of Conduct applies within all community spaces, and also applies when
+an individual is officially representing the community in public spaces.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported to the community leaders responsible for enforcement at
+andrew@fuaran.com. All complaints will be reviewed and investigated
+promptly and fairly.
+
+All community leaders are obligated to respect the privacy and security of the
+reporter of any incident.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage],
+version 2.1, available at
+[https://www.contributor-covenant.org/version/2/1/code_of_conduct.html][v2.1].
+
+For answers to common questions about this code of conduct, see the FAQ at
+[https://www.contributor-covenant.org/faq][FAQ].
+
+[homepage]: https://www.contributor-covenant.org
+[v2.1]: https://www.contributor-covenant.org/version/2/1/code_of_conduct.html
+[FAQ]: https://www.contributor-covenant.org/faq