microcosm-emitter 0.2.0__tar.gz

microcosm_emitter-0.2.0/.github/workflows/ci.yml

@@ -0,0 +1,99 @@
+name: Verify emitter
+
+# Called by pr.yaml for every pull request and by push.yaml before tagging and
+# publishing a release commit.
+on:
+  workflow_call:
+
+permissions:
+  contents: read
+
+jobs:
+  quality:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4
+      - uses: astral-sh/setup-uv@d0d8abe699bfb85fec6de9f7adb5ae17292296ff # v6
+        with:
+          python-version: "3.13"
+      - run: uv sync --locked
+      - run: bash tools/check-quality.sh
+
+  tests:
+    name: Tests (${{ matrix.os }}, Python ${{ matrix.python }})
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, macos-latest]
+        python: ["3.13", "3.14"]
+    steps:
+      - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4
+      - uses: astral-sh/setup-uv@d0d8abe699bfb85fec6de9f7adb5ae17292296ff # v6
+        with:
+          python-version: ${{ matrix.python }}
+      - run: uv sync --locked
+      - run: uv run --no-sync pytest -m "not collector"
+      - run: bash tools/check-artifacts.sh
+
+  build-packages:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4
+      - uses: astral-sh/setup-uv@d0d8abe699bfb85fec6de9f7adb5ae17292296ff # v6
+        with:
+          python-version: "3.13"
+      - run: uv sync --locked
+      - run: bash tools/check-artifacts.sh
+      - uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4
+        with:
+          name: distributions
+          path: dist/*
+          if-no-files-found: error
+
+  collector:
+    needs: build-packages
+    runs-on: ubuntu-latest
+    services:
+      postgres:
+        image: postgres:16-alpine
+        env:
+          POSTGRES_PASSWORD: postgres
+          POSTGRES_DB: telemetry_test
+        ports:
+          - 5432:5432
+        options: >-
+          --health-cmd "pg_isready -U postgres -d telemetry_test"
+          --health-interval 5s --health-timeout 5s --health-retries 10
+    env:
+      TEST_DATABASE_URL: postgresql+psycopg://postgres:postgres@127.0.0.1:5432/telemetry_test
+    steps:
+      - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4
+      - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4
+        with:
+          repository: PolicyEngine/calibration-diagnostics
+          ref: 280459c8d782658b3fb6098b27e9acba11af29d8
+          path: .collector
+          persist-credentials: false
+      - uses: astral-sh/setup-uv@d0d8abe699bfb85fec6de9f7adb5ae17292296ff # v6
+        with:
+          python-version: "3.13"
+      - uses: actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093 # v4
+        with:
+          name: distributions
+          path: dist
+      - run: bash tools/check-collector.sh
+
+  reader:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4
+      - uses: oven-sh/setup-bun@0c5077e51419868618aeaa5fe8019c62421857d6 # v2
+        with:
+          bun-version: "1.4.2"
+      - run: bash tools/check-reader.sh
+      - uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4
+        with:
+          name: orrery-reader
+          path: reader-dist/*.tgz
+          if-no-files-found: error

microcosm_emitter-0.2.0/.github/workflows/pr.yaml

@@ -0,0 +1,52 @@
+name: Pull request
+
+on:
+  pull_request:
+
+# A new push to a pull request supersedes the run on its previous head.
+concurrency:
+  group: ${{ github.workflow }}-${{ github.event.pull_request.number }}
+  cancel-in-progress: true
+
+permissions:
+  contents: read
+
+jobs:
+  lint-workflows:
+    name: Lint workflows
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4
+        with:
+          persist-credentials: false
+      # rhysd/actionlint 1.7.12, which also runs shellcheck on `run:` steps.
+      - uses: docker://rhysd/actionlint@sha256:b1934ee5f1c509618f2508e6eb47ee0d3520686341fec936f3b79331f9315667
+        with:
+          args: -color
+
+  changelog:
+    name: Check changelog fragment
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4
+        with:
+          persist-credentials: false
+      - uses: astral-sh/setup-uv@d0d8abe699bfb85fec6de9f7adb5ae17292296ff # v6
+        with:
+          python-version: "3.13"
+      - run: bash tools/check-changelog.sh
+
+  verify:
+    uses: ./.github/workflows/ci.yml
+
+  # The main ruleset requires this check by name.
+  required:
+    name: Required checks
+    if: always()
+    needs: [lint-workflows, changelog, verify]
+    runs-on: ubuntu-latest
+    steps:
+      - name: Require all validation jobs to succeed
+        env:
+          RESULTS: ${{ join(needs.*.result, ' ') }}
+        run: test "$RESULTS" = "success success success"

microcosm_emitter-0.2.0/.github/workflows/push.yaml

@@ -0,0 +1,97 @@
+name: Push
+
+on:
+  push:
+    branches: [main]
+
+permissions:
+  contents: read
+
+# Every merge runs this workflow twice. On the merge commit, versioning commits
+# the new version and changelog as "Update microcosm-emitter" with the
+# PolicyEngine GitHub App token: unlike GITHUB_TOKEN, its push starts another
+# run, and the app may bypass the main ruleset. On that release commit, the
+# remaining jobs verify, tag, then publish, each only after the one before.
+#
+# PyPI and npm trust this file by name, in the pypi environment, which only
+# main can use. Renaming it stops publication.
+jobs:
+  versioning:
+    name: Update versioning
+    if: |
+      github.repository == 'PolicyEngine/microcosm-emitter'
+      && github.event.head_commit.message != 'Update microcosm-emitter'
+    runs-on: ubuntu-latest
+    steps:
+      - id: app-token
+        uses: actions/create-github-app-token@bcd2ba49218906704ab6c1aa796996da409d3eb1 # v3.2.0
+        with:
+          app-id: ${{ secrets.APP_ID }}
+          private-key: ${{ secrets.APP_PRIVATE_KEY }}
+      - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4
+        with:
+          token: ${{ steps.app-token.outputs.token }}
+      - uses: astral-sh/setup-uv@d0d8abe699bfb85fec6de9f7adb5ae17292296ff # v6
+        with:
+          python-version: "3.13"
+      - run: bash tools/update-version.sh
+      - uses: EndBug/add-and-commit@290ea2c423ad77ca9c62ae0f5b224379612c0321 # v10
+        with:
+          add: "."
+          author_name: Github Actions[bot]
+          committer_name: Github Actions[bot]
+          message: Update microcosm-emitter
+          github_token: ${{ steps.app-token.outputs.token }}
+          fetch: false
+
+  verify:
+    if: |
+      github.repository == 'PolicyEngine/microcosm-emitter'
+      && github.event.head_commit.message == 'Update microcosm-emitter'
+    uses: ./.github/workflows/ci.yml
+
+  tag:
+    name: Publish git tag
+    needs: verify
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4
+        with:
+          fetch-depth: 0
+      - run: bash tools/publish-git-tag.sh
+
+  publish:
+    needs: tag
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093 # v4
+        with:
+          name: distributions
+          path: dist
+      - uses: pypa/gh-action-pypi-publish@dc37677b2e1c63e2034f94d8a5b11f265b73ba33 # release/v1
+        with:
+          packages-dir: dist/
+
+  publish-reader:
+    needs: [verify, publish]
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      contents: read
+      id-token: write
+    steps:
+      - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4
+      - uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4
+        with:
+          node-version: "24"
+          registry-url: "https://registry.npmjs.org"
+      - uses: actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093 # v4
+        with:
+          name: orrery-reader
+          path: reader-dist
+      - run: bash tools/publish-reader.sh

microcosm_emitter-0.2.0/.gitignore

@@ -0,0 +1,12 @@
+.venv/
+__pycache__/
+*.py[cod]
+.pytest_cache/
+.ruff_cache/
+dist/
+.coverage
+.collector/
+.test-artifacts/
+node_modules/
+reader-dist/
+typescript/orrery/dist/

microcosm_emitter-0.2.0/AGENTS.md

@@ -0,0 +1,10 @@
+# Development instructions
+
+- Use uv, Python 3.13+, pytest, and Ruff. Keep workflows as single-command calls to Bash scripts when shell logic has multiple lines.
+- The generic runtime must not import telemetry or Microcosm. The telemetry client must not import service implementation, database, or authentication modules.
+- Graph adapters must not import service, database, authentication or HTTP code. Inventory hashing, durable enqueue, receipt lookup and retries run in the separate local emitter service; no direct-database fallback.
+- Publish only the `microcosm-emitter` distribution. Keep the generic host and required telemetry library internally separate under `microcosm_emitter`; do not introduce standalone telemetry packages or optional telemetry installation.
+- Python databases use SQLAlchemy declarative ORM and Alembic exclusively. No handwritten SQL, direct-driver persistence, create_all(), schema repair, or pre-Alembic adoption. TypeScript database work, if introduced, must use Drizzle ORM and Drizzle Kit migrations.
+- Tests use temporary databases created through real migrations, synthetic credentials, and loopback network services. Never use ambient credentials or contact the production collector in tests.
+- Preserve the existing collector protocol; do not add a general hosted events API.
+- Push feature branches and open PRs; do not push directly to main. Do not automatically merge or monitor queued checks.

microcosm_emitter-0.2.0/CHANGELOG.md

@@ -0,0 +1,28 @@
+## [0.2.0] - 2026-10-14
+
+### Added
+
+- Extract the local-service host, thin build adapter, and required telemetry library into the `microcosm-emitter` distribution.
+- Add independent completed-graph publication and verified Orrery document readers alongside telemetry in the local provider.
+
+### Changed
+
+- Release automatically on every merge to main: bump one shared version from the changelog fragment types, commit the changelog, run all checks, tag the commit with the bare version, then publish to PyPI and npm through trusted publishing. Pull requests now require a typed changelog fragment, and GitHub releases no longer trigger publication.
+- Define explicit types for publication inventories and results, and return a frozen record when reserving a graph upload.
+- Integrate completed-graph publication into the single microcosm-emitter package. Keep graph adapters limited to socket requests and preserve shared SQLAlchemy/Alembic persistence, telemetry lifecycle behavior and separate TypeScript readers.
+- Consolidate the process host and required telemetry library into one `microcosm-emitter` distribution, including Python imports, installed-module registration, CI, artifact verification, and publication.
+
+  Rename the GitHub project to `PolicyEngine/microcosm-emitter` and update source metadata, installation checks, and publishing documentation.
+
+  Rename the CI package-build job to `build-packages` and update its dependent jobs.
+
+### Fixed
+
+- Use a shared 15-second startup default, enforce configuration and readiness deadlines, and report safe startup failure reasons without retaining private exception details.
+- Keep graph file requests independent of telemetry acknowledgements, drain accepted requests before closing modules, and prevent older attempts from replacing newer graph publication status documents.
+- Preserve valid stage identifiers unchanged in telemetry events and heartbeats. Reject malformed stage identifiers before persistence while continuing to redact credentials from messages and details.
+- Preserve validation-refused build outcomes and caller-supplied failure codes in the telemetry service. Allow shared-host cleanup to wait until graph publication finishes. Retain only rejected producers' records locally after permanent collector HTTP client errors, and test these behaviors against the installed package and collector.
+- Keep graph publication running when a preserved directory is removed or the local queue reports an error, and record the latest status only after the queue commit.
+- Move stage tracking, event construction, and credential redaction into the separate local telemetry emitter service. Keep the build adapter limited to process startup, request serialization, socket transport, and shutdown. Commit all events from each request atomically before acknowledging it.
+
+  Wait for a successful socket ping before runtime tests send requests, and clean up the service when test setup fails. Cover delayed listening and failed initialization with regression tests.

microcosm_emitter-0.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 PolicyEngine
+
+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.

microcosm_emitter-0.2.0/PKG-INFO

@@ -0,0 +1,83 @@
+Metadata-Version: 2.5
+Name: microcosm-emitter
+Version: 0.2.0
+Summary: Local emitter process host with required build telemetry support
+Project-URL: Source, https://github.com/PolicyEngine/microcosm-emitter
+License-Expression: MIT
+License-File: LICENSE
+Requires-Python: >=3.13
+Requires-Dist: alembic<2,>=1.13.3
+Requires-Dist: httpx<1,>=0.27
+Requires-Dist: huggingface-hub<2,>=0.20
+Requires-Dist: psutil<8,>=6
+Requires-Dist: sqlalchemy<3,>=2
+Description-Content-Type: text/markdown
+
+# Microcosm emitter
+
+`microcosm-emitter` is one Python distribution containing the process host, required telemetry library and completed-graph publication library:
+
+- `microcosm_emitter.host` owns subprocess startup, a private Unix socket, explicit module loading, parent-process monitoring, and shutdown. Its code does not import telemetry, database, authentication, or Microcosm modules.
+- `microcosm_emitter.telemetry.client` is the thin build adapter. It starts the local telemetry emitter service and sends build requests, without importing the service implementation, database, or authentication libraries.
+- `microcosm_emitter.telemetry.service` interprets those requests in the separate process. It owns stage tracking, event construction, credential redaction, resource sampling, SQLAlchemy ORM persistence, Alembic migrations, authentication, and collector delivery.
+- `microcosm_emitter.orrery.client` sends graph inventory, enqueue, receipt and retry requests over the same private socket. It does not hash files, open a database, authenticate or upload.
+- `microcosm_emitter.orrery.service` validates and hashes the selected graph files, commits publication jobs, and uploads exact bytes with retry and expiring worker reservations. A graph publication requires no telemetry run registration.
+- `microcosm_emitter.core` provides service-side authentication and SQLAlchemy/Alembic persistence shared by the telemetry and graph libraries. The generic host does not import it.
+
+Installing `microcosm-emitter` always installs the telemetry library and all its dependencies. Telemetry is not a standalone distribution or an optional extra. The package keeps import boundaries between the host, adapter, and service implementation; they do not need separate installation or publication.
+
+The build process imports only the adapter, not the service implementation. It supplies run metadata, its existing queue path, and build identity. The adapter starts a separate local telemetry emitter service process automatically and sends requests over a private Unix socket. The adapter does not track stages, construct events, or redact telemetry. Imports alone create no processes, sockets, files, or network requests.
+
+## Delivery and persistence
+
+The service interprets requests such as a stage change or build failure, timestamps and redacts the resulting events, and saves them before acknowledging the socket request. A stage change can complete one stage and start another; both events commit in one SQLAlchemy ORM transaction, and the service changes its stage state only after that transaction succeeds. Periodic retention maintenance runs outside this acknowledgement path.
+
+The adapter bounds socket calls and reports telemetry failures without failing the build. It converts Python arguments into JSON but does not process their telemetry meaning. Network requests run on the service worker, outside the message-handling lock.
+
+`block()` finishes the current stage and records that validation checks refused the build, including the phase, check identifiers, failure count and optional check statuses. `fail(error_code=...)` preserves the caller's failure code alongside the exception type and failure class. Microcosm classifies interruptions, process termination and memory failures; this package forwards those classifications rather than duplicating them. Both outcomes finish telemetry, so later heartbeat or parent-exit handling cannot replace them.
+
+The service uses the existing Hugging Face credential from the environment or local login cache. The collector validates PolicyEngine membership before issuing a short-lived write credential. Missing or rejected credentials permanently mark that producer's events as local-only. Permanent HTTP client errors when registering a run or uploading events also keep only the affected producer's records local; HTTP 408, 429, server errors and network failures remain retryable. HTTP 401 invalidates the short-lived credential for renewal. The production destination belongs to the package; development overrides accept loopback addresses only.
+
+The queue upgrades the existing `20261007_01` Alembic revision to `20261008_02`, adding graph-job records without changing producer sequences, event IDs or upload eligibility. Unversioned databases are rejected without schema modification. There is no raw SQL, automatic schema adoption, or parallel legacy implementation. The hosted telemetry collector and calibration dashboard do not change.
+
+## Graph publication
+
+`GraphPublicationClient.start()` starts the graph module in a separate local emitter service process. `inventory()` asks that process to hash an explicit set of allowed graph files; `enqueue()` returns a pending receipt only after the job commits. `receipt()` reads its result and `retry()` makes a pending job eligible again. Startup or socket failures return an unavailable result, not a claim that a job was saved; the build adapter never writes a fallback database.
+
+Graph requests allow up to 30 seconds for bounded file validation and hashing; telemetry acknowledgements, readiness probes and close requests keep their existing short timeout. Very slow storage can still exceed the graph request limit, so a timeout is not proof that a late service-side commit did or did not occur. Repeating an enqueue with the same publication ID and inventory is idempotent.
+
+The host can also start telemetry and graph modules together with `start_services()`. Each module has an independent worker, so a slow graph upload does not block telemetry requests. Construct the telemetry adapter with `close_service_on_finish=False` when a build must publish graphs after recording completion, failure or refusal. Telemetry still finishes, but explicit outer cleanup closes the shared host after graph requests; standalone adapters close automatically by default. A module-specific graph client does not own shared-host shutdown. Both libraries share an existing HF credential and short-lived collector session, but graph jobs remain pending independently of telemetry event retention or local-only upload eligibility.
+
+Preserve the selected source files until publication succeeds. `microcosm-emitter-publish-graph` asks the service to retry a publication by ID and can re-enqueue a preserved directory on another machine. It never rewrites the original build receipt; the queue and separate latest-status file record retries.
+
+The existing TypeScript package `@policyengine/microcosm-provider-orrery` reads immutable published graph files on a server or in a browser. It remains separate from the Python distribution and does not change the hosted telemetry API.
+
+## Development
+
+Use Python 3.13 or 3.14 on Linux or macOS.
+
+```bash
+uv sync --locked
+bash tools/check-quality.sh
+uv run --no-sync pytest -m 'not collector'
+bash tools/check-artifacts.sh
+bash tools/check-reader.sh
+bash tools/check-changelog.sh
+```
+
+Tests isolate ambient credentials and use synthetic identities. The artifact check builds one source archive and wheel, installs that wheel into a clean environment away from the source checkout, verifies import boundaries, and exercises telemetry-only, graph-only and combined service startup with packaged migrations. Reader checks cover tests, formatting, types, build and an isolated tarball installation; they do not inspect visual styling.
+
+The collector compatibility job tests the installed wheel against a pinned dashboard collector and disposable PostgreSQL. It covers the HTTP exchange, event ingestion, blocked outcomes and supplied failure codes in dashboard run documents, rejected identities, and duplicate delivery after a lost acknowledgement. Local execution requires that pinned collector checkout and a loopback test database; `tools/check-collector.sh` verifies these inputs. Never point this test at a deployed database. The pin verifies source compatibility, not which revision the hosted collector currently runs.
+
+## Publication
+
+Every merge to `main` releases the Python distribution `microcosm-emitter` to PyPI and the TypeScript reader `@policyengine/microcosm-provider-orrery` to npm at one shared version. Each pull request adds a changelog fragment named `changelog.d/<name>.<type>.md`, where the type is `breaking`, `added`, `changed`, `fixed` or `removed`; `tools/check-changelog.sh` refuses a pull request without one.
+
+`push.yaml` runs twice for each merge:
+
+1. On the merge commit, it bumps the version in `pyproject.toml`, both `package.json` files and `uv.lock`: a major bump for a breaking fragment, a minor bump for an added or removed fragment, and a patch bump otherwise. It collects the fragments into `CHANGELOG.md` and commits the result as "Update microcosm-emitter" using the PolicyEngine GitHub App, which may bypass the `main` ruleset.
+2. On that commit, it runs every CI check, tags the commit with the bare version (for example `0.2.0`), publishes the tested wheel and source archive to PyPI, and then publishes the tested reader tarball to npm. Each step starts only after the one before succeeds.
+
+Both registries accept uploads only through trusted publishing from `push.yaml` in the `pypi` environment, which only `main` can use. CI holds no long-lived registry token. Renaming the workflow or the environment stops publication until both registries' trusted-publisher settings change to match.
+
+No hosted-service deployment or consumer activation follows from publishing this package.

microcosm_emitter-0.2.0/README.md

@@ -0,0 +1,68 @@
+# Microcosm emitter
+
+`microcosm-emitter` is one Python distribution containing the process host, required telemetry library and completed-graph publication library:
+
+- `microcosm_emitter.host` owns subprocess startup, a private Unix socket, explicit module loading, parent-process monitoring, and shutdown. Its code does not import telemetry, database, authentication, or Microcosm modules.
+- `microcosm_emitter.telemetry.client` is the thin build adapter. It starts the local telemetry emitter service and sends build requests, without importing the service implementation, database, or authentication libraries.
+- `microcosm_emitter.telemetry.service` interprets those requests in the separate process. It owns stage tracking, event construction, credential redaction, resource sampling, SQLAlchemy ORM persistence, Alembic migrations, authentication, and collector delivery.
+- `microcosm_emitter.orrery.client` sends graph inventory, enqueue, receipt and retry requests over the same private socket. It does not hash files, open a database, authenticate or upload.
+- `microcosm_emitter.orrery.service` validates and hashes the selected graph files, commits publication jobs, and uploads exact bytes with retry and expiring worker reservations. A graph publication requires no telemetry run registration.
+- `microcosm_emitter.core` provides service-side authentication and SQLAlchemy/Alembic persistence shared by the telemetry and graph libraries. The generic host does not import it.
+
+Installing `microcosm-emitter` always installs the telemetry library and all its dependencies. Telemetry is not a standalone distribution or an optional extra. The package keeps import boundaries between the host, adapter, and service implementation; they do not need separate installation or publication.
+
+The build process imports only the adapter, not the service implementation. It supplies run metadata, its existing queue path, and build identity. The adapter starts a separate local telemetry emitter service process automatically and sends requests over a private Unix socket. The adapter does not track stages, construct events, or redact telemetry. Imports alone create no processes, sockets, files, or network requests.
+
+## Delivery and persistence
+
+The service interprets requests such as a stage change or build failure, timestamps and redacts the resulting events, and saves them before acknowledging the socket request. A stage change can complete one stage and start another; both events commit in one SQLAlchemy ORM transaction, and the service changes its stage state only after that transaction succeeds. Periodic retention maintenance runs outside this acknowledgement path.
+
+The adapter bounds socket calls and reports telemetry failures without failing the build. It converts Python arguments into JSON but does not process their telemetry meaning. Network requests run on the service worker, outside the message-handling lock.
+
+`block()` finishes the current stage and records that validation checks refused the build, including the phase, check identifiers, failure count and optional check statuses. `fail(error_code=...)` preserves the caller's failure code alongside the exception type and failure class. Microcosm classifies interruptions, process termination and memory failures; this package forwards those classifications rather than duplicating them. Both outcomes finish telemetry, so later heartbeat or parent-exit handling cannot replace them.
+
+The service uses the existing Hugging Face credential from the environment or local login cache. The collector validates PolicyEngine membership before issuing a short-lived write credential. Missing or rejected credentials permanently mark that producer's events as local-only. Permanent HTTP client errors when registering a run or uploading events also keep only the affected producer's records local; HTTP 408, 429, server errors and network failures remain retryable. HTTP 401 invalidates the short-lived credential for renewal. The production destination belongs to the package; development overrides accept loopback addresses only.
+
+The queue upgrades the existing `20261007_01` Alembic revision to `20261008_02`, adding graph-job records without changing producer sequences, event IDs or upload eligibility. Unversioned databases are rejected without schema modification. There is no raw SQL, automatic schema adoption, or parallel legacy implementation. The hosted telemetry collector and calibration dashboard do not change.
+
+## Graph publication
+
+`GraphPublicationClient.start()` starts the graph module in a separate local emitter service process. `inventory()` asks that process to hash an explicit set of allowed graph files; `enqueue()` returns a pending receipt only after the job commits. `receipt()` reads its result and `retry()` makes a pending job eligible again. Startup or socket failures return an unavailable result, not a claim that a job was saved; the build adapter never writes a fallback database.
+
+Graph requests allow up to 30 seconds for bounded file validation and hashing; telemetry acknowledgements, readiness probes and close requests keep their existing short timeout. Very slow storage can still exceed the graph request limit, so a timeout is not proof that a late service-side commit did or did not occur. Repeating an enqueue with the same publication ID and inventory is idempotent.
+
+The host can also start telemetry and graph modules together with `start_services()`. Each module has an independent worker, so a slow graph upload does not block telemetry requests. Construct the telemetry adapter with `close_service_on_finish=False` when a build must publish graphs after recording completion, failure or refusal. Telemetry still finishes, but explicit outer cleanup closes the shared host after graph requests; standalone adapters close automatically by default. A module-specific graph client does not own shared-host shutdown. Both libraries share an existing HF credential and short-lived collector session, but graph jobs remain pending independently of telemetry event retention or local-only upload eligibility.
+
+Preserve the selected source files until publication succeeds. `microcosm-emitter-publish-graph` asks the service to retry a publication by ID and can re-enqueue a preserved directory on another machine. It never rewrites the original build receipt; the queue and separate latest-status file record retries.
+
+The existing TypeScript package `@policyengine/microcosm-provider-orrery` reads immutable published graph files on a server or in a browser. It remains separate from the Python distribution and does not change the hosted telemetry API.
+
+## Development
+
+Use Python 3.13 or 3.14 on Linux or macOS.
+
+```bash
+uv sync --locked
+bash tools/check-quality.sh
+uv run --no-sync pytest -m 'not collector'
+bash tools/check-artifacts.sh
+bash tools/check-reader.sh
+bash tools/check-changelog.sh
+```
+
+Tests isolate ambient credentials and use synthetic identities. The artifact check builds one source archive and wheel, installs that wheel into a clean environment away from the source checkout, verifies import boundaries, and exercises telemetry-only, graph-only and combined service startup with packaged migrations. Reader checks cover tests, formatting, types, build and an isolated tarball installation; they do not inspect visual styling.
+
+The collector compatibility job tests the installed wheel against a pinned dashboard collector and disposable PostgreSQL. It covers the HTTP exchange, event ingestion, blocked outcomes and supplied failure codes in dashboard run documents, rejected identities, and duplicate delivery after a lost acknowledgement. Local execution requires that pinned collector checkout and a loopback test database; `tools/check-collector.sh` verifies these inputs. Never point this test at a deployed database. The pin verifies source compatibility, not which revision the hosted collector currently runs.
+
+## Publication
+
+Every merge to `main` releases the Python distribution `microcosm-emitter` to PyPI and the TypeScript reader `@policyengine/microcosm-provider-orrery` to npm at one shared version. Each pull request adds a changelog fragment named `changelog.d/<name>.<type>.md`, where the type is `breaking`, `added`, `changed`, `fixed` or `removed`; `tools/check-changelog.sh` refuses a pull request without one.
+
+`push.yaml` runs twice for each merge:
+
+1. On the merge commit, it bumps the version in `pyproject.toml`, both `package.json` files and `uv.lock`: a major bump for a breaking fragment, a minor bump for an added or removed fragment, and a patch bump otherwise. It collects the fragments into `CHANGELOG.md` and commits the result as "Update microcosm-emitter" using the PolicyEngine GitHub App, which may bypass the `main` ruleset.
+2. On that commit, it runs every CI check, tags the commit with the bare version (for example `0.2.0`), publishes the tested wheel and source archive to PyPI, and then publishes the tested reader tarball to npm. Each step starts only after the one before succeeds.
+
+Both registries accept uploads only through trusted publishing from `push.yaml` in the `pypi` environment, which only `main` can use. CI holds no long-lived registry token. Renaming the workflow or the environment stops publication until both registries' trusted-publisher settings change to match.
+
+No hosted-service deployment or consumer activation follows from publishing this package.

microcosm_emitter-0.2.0/conftest.py

@@ -0,0 +1,29 @@
+"""Tests cannot consume ambient credentials or send traffic to the collector."""
+
+from urllib.parse import urlsplit
+
+import pytest
+
+
+@pytest.fixture(autouse=True)
+def isolate_credentials_and_network(tmp_path, monkeypatch):
+    for name in ("HF_TOKEN", "HUGGINGFACE_TOKEN", "HUGGING_FACE_HUB_TOKEN"):
+        monkeypatch.delenv(name, raising=False)
+    hf_home = tmp_path / "hf"
+    monkeypatch.setenv("HF_HOME", str(hf_home))
+    monkeypatch.setenv("HF_TOKEN_PATH", str(hf_home / "token"))
+    from huggingface_hub import constants
+
+    monkeypatch.setattr(constants, "HF_TOKEN_PATH", str(hf_home / "token"))
+    from microcosm_emitter.core import auth
+    from microcosm_emitter.telemetry.service import collector
+
+    real_post = collector._http_post
+
+    def loopback_post(url, *args, **kwargs):
+        if urlsplit(url).hostname not in {"localhost", "127.0.0.1", "::1"}:
+            raise AssertionError("Tests must not contact a hosted collector")
+        return real_post(url, *args, **kwargs)
+
+    monkeypatch.setattr(collector, "_http_post", loopback_post)
+    monkeypatch.setattr(auth, "_http_post", loopback_post)

microcosm_emitter-0.2.0/package.json

@@ -0,0 +1,15 @@
+{
+  "name": "@policyengine/microcosm-provider-orrery",
+  "version": "0.2.0",
+  "private": true,
+  "type": "module",
+  "description": "Pinned-source development entry points; publish the built package from typescript/orrery",
+  "exports": {
+    "./contract": "./typescript/orrery/src/contract.ts",
+    "./browser": "./typescript/orrery/src/browser.ts",
+    "./server": "./typescript/orrery/src/server.ts"
+  },
+  "peerDependencies": {
+    "@axiom-foundation/orrery": "0.6.1"
+  }
+}

microcosm_emitter-0.2.0/pyproject.toml

@@ -0,0 +1,79 @@
+[project]
+name = "microcosm-emitter"
+version = "0.2.0"
+description = "Local emitter process host with required build telemetry support"
+readme = "README.md"
+requires-python = ">=3.13"
+license = "MIT"
+dependencies = [
+    "alembic>=1.13.3,<2",
+    "sqlalchemy>=2,<3",
+    "huggingface-hub>=0.20,<2",
+    "psutil>=6,<8",
+    "httpx>=0.27,<1",
+]
+
+[project.urls]
+Source = "https://github.com/PolicyEngine/microcosm-emitter"
+
+[project.entry-points."microcosm.emitter.modules"]
+telemetry = "microcosm_emitter.telemetry.service:create_module"
+orrery = "microcosm_emitter.orrery.service:create_module"
+
+[project.scripts]
+microcosm-emitter-publish-graph = "microcosm_emitter.orrery.cli:main"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/microcosm_emitter"]
+
+[dependency-groups]
+dev = ["pytest>=8,<9", "ruff>=0.11,<1", "build>=1,<2", "twine>=7,<8", "pyyaml>=6,<7"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = "-q --import-mode=importlib"
+markers = ["collector: requires the pinned collector and disposable PostgreSQL"]
+
+[tool.ruff]
+line-length = 88
+target-version = "py313"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "N", "W", "UP", "B"]
+ignore = ["E501"]
+
+[tool.towncrier]
+directory = "changelog.d"
+filename = "CHANGELOG.md"
+title_format = "## [{version}] - {project_date}"
+issue_format = ""
+underlines = ["", "", ""]
+
+[[tool.towncrier.type]]
+directory = "breaking"
+name = "Breaking changes"
+showcontent = true
+
+[[tool.towncrier.type]]
+directory = "added"
+name = "Added"
+showcontent = true
+
+[[tool.towncrier.type]]
+directory = "changed"
+name = "Changed"
+showcontent = true
+
+[[tool.towncrier.type]]
+directory = "fixed"
+name = "Fixed"
+showcontent = true
+
+[[tool.towncrier.type]]
+directory = "removed"
+name = "Removed"
+showcontent = true

microcosm_emitter-0.2.0/src/microcosm_emitter/__init__.py

@@ -0,0 +1 @@
+"""Local emitter host and required telemetry library, without import side effects."""

microcosm_emitter-0.2.0/src/microcosm_emitter/core/__init__.py

@@ -0,0 +1 @@
+"""Shared provider services; importing this package has no runtime side effects."""

microcosm_emitter-0.2.0/src/microcosm_emitter/core/alembic/env.py

@@ -0,0 +1,28 @@
+"""Alembic environment for the local telemetry spool."""
+
+from alembic import context
+from sqlalchemy.engine import Connection
+
+from microcosm_emitter.core.models import SpoolModel
+
+_MISSING_CONNECTION_ERROR = (
+    "telemetry spool migrations require a programmatically supplied connection"
+)
+
+
+def run_migrations() -> None:
+    """Run migrations on the connection supplied by the emitter service."""
+
+    connection = context.config.attributes.get("connection")
+    if not isinstance(connection, Connection):
+        raise RuntimeError(_MISSING_CONNECTION_ERROR)
+    context.configure(
+        connection=connection,
+        target_metadata=SpoolModel.metadata,
+        render_as_batch=True,
+    )
+    with context.begin_transaction():
+        context.run_migrations()
+
+
+run_migrations()