noeta 1.0.0rc1__tar.gz

noeta-1.0.0rc1/.editorconfig

@@ -0,0 +1,25 @@
+# EditorConfig — https://editorconfig.org
+root = true
+
+[*]
+charset = utf-8
+end_of_line = lf
+insert_final_newline = true
+trim_trailing_whitespace = true
+indent_style = space
+
+# Python
+[*.py]
+indent_size = 4
+
+# Web sources, config, and data
+[*.{js,jsx,ts,tsx,css,html,json,yml,yaml,toml}]
+indent_size = 2
+
+# Markdown — keep trailing whitespace (two-space line breaks are significant)
+[*.md]
+trim_trailing_whitespace = false
+
+# Makefiles require real tabs
+[Makefile]
+indent_style = tab

noeta-1.0.0rc1/.env.example

@@ -0,0 +1,23 @@
+# Live model configuration for `make e2e` and `make eval`.
+#
+# Copy this file to `.env` (git-ignored) and fill in the values below:
+#
+#     cp .env.example .env
+#     make e2e
+#
+# One gateway, one key, one base (the host, without /v1); the live tests reach
+# three endpoints under it:
+#   <base>/v1/messages          (anthropic)
+#   <base>/v1/responses         (openai_responses)
+#   <base>/v1/chat/completions  (openai_compat)
+#
+# Missing any of base/key/model auto-skips every live test (CI never runs them).
+# An already-set environment variable overrides the file, so you can also do:
+#   NOETA_LIVE_MODEL=other-model uv run pytest -m live
+
+NOETA_LIVE_BASE_URL=https://your-gateway.example.com
+NOETA_LIVE_API_KEY=your-rotated-key
+NOETA_LIVE_MODEL=your-model-id
+
+# Optional:
+# NOETA_LIVE_MAX_TOKENS=1024

noeta-1.0.0rc1/.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,42 @@
+---
+name: Bug report
+about: Report something that behaves incorrectly in noeta
+title: "[bug] "
+labels: bug
+assignees: ''
+---
+
+## What happened
+
+A clear, concise description of the incorrect behavior.
+
+## Steps to reproduce
+
+1. …
+2. …
+3. …
+
+Include the smallest command, program or config that triggers it. If it concerns what the
+model was sent or did, the output of `noeta -p --output-format stream-json --verbose` helps.
+
+## Expected behavior
+
+What you expected instead. If Claude Code behaves differently, say how: a difference in what
+the model sees is a bug.
+
+## Environment
+
+- OS:
+- Python version:
+- noeta version / commit: <!-- e.g. 1.0.0.dev0 @ <sha> -->
+- Install: <!-- uv tool install from the repository / a checkout / pip -->
+- Provider and model: <!-- anthropic | openai_compat | openai_responses, model id -->
+- Store: <!-- sqlite (default) | postgres -->
+
+## Logs
+
+Relevant output or tracebacks. Redact API keys, tokens and sensitive task content.
+
+```
+<paste logs here>
+```

noeta-1.0.0rc1/.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,5 @@
+blank_issues_enabled: true
+contact_links:
+  - name: Report a security vulnerability
+    url: https://github.com/initxy/noeta/security/advisories/new
+    about: Report vulnerabilities privately, never in a public issue (see SECURITY.md).

noeta-1.0.0rc1/.github/ISSUE_TEMPLATE/feature_request.md

@@ -0,0 +1,30 @@
+---
+name: Feature request
+about: Propose a change or addition to noeta
+title: "[feat] "
+labels: enhancement
+assignees: ''
+---
+
+## Problem / motivation
+
+What are you trying to do, and where does noeta get in the way? Describe the need, not only
+the solution.
+
+## Proposed solution
+
+What you would like noeta to do. If Claude Code already does it, say how. If it could be a
+plugin (`docs/guides/plugins.md`), say why it should be built in.
+
+## Alternatives considered
+
+Other approaches you weighed and why they fall short. If a decision in `docs/adr/` stands in
+the way, name it.
+
+## Area
+
+- [ ] kernel (`noeta/core`)
+- [ ] a plugin (`noeta/plugins/...`)
+- [ ] backends (providers, exec envs, stores)
+- [ ] ways in (HTTP, ACP, stream-json) or the `noeta` command
+- [ ] docs / other

noeta-1.0.0rc1/.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,32 @@
+## Summary
+
+What this change does and why. Lead with the conclusion.
+
+## Kind
+
+- [ ] behavior (with a test that fails before it)
+- [ ] structure only (no behavior change)
+- [ ] docs
+
+Structure and behavior never share a pull request (see [CONTRIBUTING.md](../CONTRIBUTING.md)).
+
+## Spec / decision
+
+Link the spec in `docs/specs/` this implements, or "none — no open decision". If a decision in
+`docs/adr/` changes, link the new ADR that refines or supersedes it.
+
+## How verified
+
+```bash
+make check   # lint, mypy, layering, tests with coverage, examples, doc hygiene
+```
+
+Paste the result. For model-facing text or provider wire changes, also `make eval` /
+`make parity` and the relevant `make e2e` tests. Say what could not be verified and why.
+
+## Checklist
+
+- [ ] `make check` passes.
+- [ ] Docs the change makes wrong are fixed in it (`CONTEXT.md`, `docs/`, `CHANGELOG.md` Unreleased).
+- [ ] If this implements a spec: its status, Plan checkboxes and Progress log are up to date.
+- [ ] A human owner has read this change and can answer review questions about it.

noeta-1.0.0rc1/.github/workflows/ci.yml

@@ -0,0 +1,102 @@
+name: ci
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+permissions:
+  contents: read
+
+# One run per ref; a newer push to a PR cancels the stale run. Runs on main
+# are never cancelled so every merged commit gets a verdict.
+concurrency:
+  group: ci-${{ github.ref }}
+  cancel-in-progress: ${{ github.event_name == 'pull_request' }}
+
+jobs:
+  test:
+    name: make check (Python ${{ matrix.python-version }})
+    runs-on: ubuntu-latest
+    timeout-minutes: 30
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.11", "3.12", "3.13"]
+    services:
+      # The store contract tests run their Postgres parameter when
+      # NOETA_TEST_POSTGRES_DSN is set (skipped otherwise).
+      postgres:
+        image: postgres:16
+        env:
+          POSTGRES_PASSWORD: postgres
+        ports:
+          - 5432:5432
+        options: >-
+          --health-cmd pg_isready
+          --health-interval 5s
+          --health-timeout 5s
+          --health-retries 10
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v6
+        with:
+          python-version: ${{ matrix.python-version }}
+          enable-cache: true
+
+      - name: Install ripgrep
+        # No tool shells out to `rg` any more (search runs through Bash, and the suite does not
+        # need it); installed so a `Bash` search in a test finds what a developer machine has.
+        run: sudo apt-get update -qq && sudo apt-get install -y -qq ripgrep
+
+      - name: make check
+        env:
+          NOETA_TEST_POSTGRES_DSN: postgresql://postgres:postgres@localhost:5432/postgres
+        run: make check
+
+  cluster:
+    name: make cluster (workers on Postgres under faults)
+    runs-on: ubuntu-latest
+    timeout-minutes: 25
+    services:
+      postgres:
+        image: postgres:16
+        env:
+          POSTGRES_PASSWORD: postgres
+        ports:
+          - 5432:5432
+        options: >-
+          --health-cmd pg_isready
+          --health-interval 5s
+          --health-timeout 5s
+          --health-retries 10
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v6
+        with:
+          python-version: "3.12"
+          enable-cache: true
+
+      - name: Raise max_connections
+        # Every worker process keeps its own pool; the default 100 runs out
+        # (the harness's own container starts with 400). A service container
+        # takes no server flags, so set it and restart.
+        run: |
+          pg=${{ job.services.postgres.id }}
+          docker exec "$pg" psql -U postgres -c "ALTER SYSTEM SET max_connections = 400"
+          docker restart "$pg"
+          for _ in $(seq 60); do
+            docker exec "$pg" pg_isready -U postgres -h 127.0.0.1 && break
+            sleep 1
+          done
+          docker exec "$pg" psql -U postgres -tAc "SHOW max_connections"
+
+      - name: make cluster
+        env:
+          NOETA_TEST_POSTGRES_DSN: postgresql://postgres:postgres@localhost:5432/postgres
+        run: make cluster

noeta-1.0.0rc1/.github/workflows/docs.yml

@@ -0,0 +1,85 @@
+# Build the VitePress documentation site and deploy to GitHub Pages.
+#
+# Push to main (docs changes) or manual dispatch: build + deploy.
+# Pull request touching the docs: build only, so a broken page fails the PR
+# instead of the deploy after merge. Nothing is uploaded or deployed.
+# Uses actions/deploy-pages — Pages source must be set to "GitHub Actions"
+# in the repository settings (Settings → Pages → Build and deployment → Source).
+
+name: docs
+
+on:
+  push:
+    branches: [main]
+    paths:
+      - "docs/**"
+      - "!docs/specs/**"
+      - ".github/workflows/docs.yml"
+  pull_request:
+    branches: [main]
+    paths:
+      - "docs/**"
+      - "!docs/specs/**"
+      - ".github/workflows/docs.yml"
+  workflow_dispatch: {}
+
+permissions:
+  contents: read
+
+# Deploys share one queue and are never cancelled mid-flight; PR builds get
+# their own group per ref and a newer push cancels the stale one.
+concurrency:
+  group: ${{ github.event_name == 'pull_request' && format('docs-pr-{0}', github.ref) || 'pages' }}
+  cancel-in-progress: ${{ github.event_name == 'pull_request' }}
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    permissions:
+      contents: read
+      pages: write   # configure-pages reads the site's Pages settings
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: 20
+          cache: npm
+          cache-dependency-path: docs/package-lock.json
+
+      - name: Install dependencies
+        run: npm ci
+        working-directory: docs
+
+      - name: Configure Pages
+        if: github.event_name != 'pull_request'
+        id: pages
+        uses: actions/configure-pages@v5
+
+      - name: Build VitePress site
+        run: npm run build
+        working-directory: docs
+
+      - name: Upload artifact
+        if: github.event_name != 'pull_request'
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: docs/.vitepress/dist
+
+  deploy:
+    if: github.event_name != 'pull_request'
+    needs: build
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    permissions:
+      pages: write
+      id-token: write
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4

noeta-1.0.0rc1/.github/workflows/release.yml

@@ -0,0 +1,73 @@
+# Publish `noeta` to PyPI when a `v*` tag is pushed. Procedure: docs/releasing.md.
+# Auth is PyPI Trusted Publishing (OIDC); no token is stored anywhere.
+
+name: Release
+
+on:
+  push:
+    tags: ["v*"]
+  workflow_dispatch: {}
+
+permissions:
+  contents: read
+
+concurrency:
+  group: release-${{ github.ref }}
+  cancel-in-progress: false
+
+jobs:
+  # The suite on the exact commit being published: a tag can point anywhere.
+  test:
+    runs-on: ubuntu-latest
+    timeout-minutes: 30
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v6
+        with:
+          python-version: "3.12"
+      - name: Install ripgrep
+        run: sudo apt-get update -qq && sudo apt-get install -y -qq ripgrep
+      - run: make check
+
+  build:
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    steps:
+      - uses: actions/checkout@v4
+      - name: Changelog gate — the tagged version must have a dated section
+        if: startsWith(github.ref, 'refs/tags/v')
+        run: |
+          VERSION="${GITHUB_REF_NAME#v}"
+          if ! grep -Eq "^## \[${VERSION}\] - [0-9]{4}-[0-9]{2}-[0-9]{2}$" CHANGELOG.md; then
+            echo "::error::CHANGELOG.md has no dated '## [${VERSION}] - YYYY-MM-DD' section; see docs/releasing.md"
+            exit 1
+          fi
+      - uses: astral-sh/setup-uv@v6
+        with:
+          python-version: "3.12"
+      - name: Build
+        run: |
+          uv build
+          ls -l dist/
+      - name: The wheel's version is the tag's
+        if: startsWith(github.ref, 'refs/tags/v')
+        run: |
+          VERSION="${GITHUB_REF_NAME#v}"
+          ls dist/noeta-"${VERSION}"-*.whl
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    needs: [test, build]
+    if: startsWith(github.ref, 'refs/tags/v')
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    permissions:
+      id-token: write   # mint the short-lived PyPI OIDC token
+    steps:
+      - uses: actions/download-artifact@v4
+        with: { name: dist, path: dist/ }
+      - uses: astral-sh/setup-uv@v6
+      - run: uv publish --trusted-publishing always dist/*

noeta-1.0.0rc1/.gitignore

@@ -0,0 +1,73 @@
+# Claude Code local config of contributors (not part of noeta)
+.claude/
+
+# Live-test secrets (never committed)
+.env
+
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+*.egg-info/
+.venv/
+venv/
+env/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.import_linter_cache/
+.tox/
+htmlcov/
+.coverage
+.coverage.*
+dist/
+build/
+site/
+*.egg
+node_modules/
+
+# web/ test output
+web/test-results/
+web/playwright-report/
+
+# desktop/ build and test output
+desktop/build/
+desktop/release/
+desktop/test-results/
+desktop/playwright-report/
+
+# IDE / Editor
+.idea/
+.vscode/
+*.swp
+*.swo
+*~
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Local demo / scratch artifacts
+*.sqlite
+*.sqlite-shm
+*.sqlite-wal
+*.tmp.xml
+*.tmp
+
+# Local host config that may hold an api_key — ignored so a local copy can
+# never be committed.
+/noeta.config.json
+
+# prompt-regression eval run outputs
+evals/results/
+bench/jobs/
+bench/datasets/
+bench/logs/
+
+# make parity output (the replay capture and the report it writes)
+parity/out/
+parity/report.md
+
+# Claude Code's wording, even hashed, stays out of the repository
+parity/*/cc-windows.bin

noeta-1.0.0rc1/.python-version

@@ -0,0 +1 @@
+3.12

noeta-1.0.0rc1/AGENTS.md

@@ -0,0 +1,81 @@
+## Communication
+
+- Keep answers concise and direct; lead with the conclusion and the next step.
+- Don't add unrelated explanation; when unsure, state your assumptions and the risks.
+- Don't narrate what you're about to do or recap what you just did; report only what changes what the reader does next.
+- Conversation may happen in whatever language the other side uses; everything committed to the repo (see Language) is English.
+
+## Language
+
+- All repository artifacts are written in English: docs (`CONTEXT.md`, `docs/adr/`, `docs/specs/`), code comments, and identifiers. The one exception is the docs site: every page in `docs/` that the site serves (`docs/.vitepress/config.ts` lists them) has a Chinese page at the same path under `docs/zh/`, written as Chinese rather than translated, and a change to one updates both.
+- Keep technical terms in their canonical English form and spell them consistently throughout: code identifiers (function / class / file / variable names), API / library / tool / command names, file paths, and fixed architecture terms (module, interface, seam, adapter, deep module, etc.). Don't invent alternate names or switch between synonyms.
+- Write clear, idiomatic English prose — not word-for-word translation from another language.
+- Pick one spelling per term and use it everywhere; don't mix variants.
+- Naming is enforced by `scripts/lint-naming.py` (in `make check`); the banned names and the canonical `Task` / `root_task_id` are in `CONTEXT.md`'s `Naming:` entries.
+
+## Context / ADR
+
+- Read `CONTEXT.md` first whenever you touch domain concepts, system boundaries, or stable conventions. A package with its own `AGENTS.md` keeps its module-only concepts there.
+- Read `docs/adr/` (start at `docs/adr/index.md`) first whenever a long-term architecture trade-off is involved; never rely on an ADR marked `superseded`, and read the ADRs listed under its `Refined by`.
+- Code is the single source of truth for "what is." When docs and code disagree, trust the code and fix the docs.
+- One fact, one home: never state the same fact in two docs — link instead. The docs site is the home of explanations for users; `CONTEXT.md` and ADRs are for contributors and the site links to them. A change that invalidates a `CONTEXT.md` entry or ADR updates it in the same task.
+- Write docs lean: a `CONTEXT.md` or `AGENTS.md` line exists only if code can't tell an agent the same thing quickly; point at code by repo path instead of restating it. An ADR only for a shipped decision that is costly to reverse; changing one is a new ADR that refines or supersedes it, never an amendment in place. `scripts/check-docs.sh` holds the budgets and formats — trim, don't raise them. When unsure, don't write it.
+- Code comments carry only constraints the code can't show — never a `docs/specs/` reference (one-shot artifacts). Code needn't cite ADRs; where a comment names one it is plain prose, not a contract.
+- Archived specs (`docs/specs/archive/`) are construction history — never read them as a description of the current system.
+
+## Task flow
+
+- Before starting, run `make check`. Red that isn't yours → report it before anything else.
+- When the idea isn't clear yet, shape before code: ask one question at a time, each with a recommended answer and its reasoning; look up what code and docs can answer instead of asking. Converged = no open decision that would change the implementation path, boundary, or acceptance criteria. ("Just recommend" → answer straight, flagging the assumptions.)
+- Shaping red lines: no implementation code and no spec before the design converges; a finished spec doesn't slide into implementation — starting is a separate decision.
+- Record decisions in the spec's `Decisions` as they settle — not yet in `CONTEXT.md` or `docs/adr/`; those are distilled at review wrap-up from what survived. One-off details are not persisted.
+- Write the spec per `docs/specs/TEMPLATE.md` at `docs/specs/<YYYY-MM-DD>-<slug>.md`: `active` if implementation starts now, `proposed` if queued. A terminal status (`done` / `superseded` / `dropped`) and the move into `docs/specs/archive/` are one action.
+- A change with no open decision (a bug fix with clear expected behavior, a small change inside one module) needs no spec: implement directly and put the why in the commit message.
+- Implement against the spec: flip it `active` (set `owner` when others may work in parallel); tick Plan tasks as they complete; log progress, decision changes, and friction in its Progress log. For large tasks with clean boundaries, split work across subagents while the main agent integrates and verifies.
+- For architecture improvements, refactoring direction, and module design, start from the existing decisions (`docs/adr/`) and the engineering constraints below.
+- done = every acceptance criterion met + all automated gates green. Both required.
+- Before merge, review per `docs/reviewing.md`; merging archives the spec and distills long-term knowledge.
+- Resume across sessions from the spec alone; write no separate handoff doc. A spec-less change that spans sessions leaves its state in the branch's commit messages.
+
+## Verbs
+
+- install: `make install` (uv sync with every extra; first time)
+- test: `make test`
+- lint: `make lint`
+- build: `make build` (wheel and sdist into `dist/`)
+- e2e: `make e2e` — `-m live` tests against a real model (providers, ACP); needs credentials, never part of `check`
+- eval: `make eval` — prompt-regression scenarios against a real model, compared to `evals/baseline.json`; `make eval-baseline` re-records it; needs credentials, never part of `check`
+- parity: `make parity` — noeta replayed offline through Claude Code's recorded scenarios, every request difference in `parity/report.md` (`scripts/parity/README.md`); never part of `check`
+- cluster: `make cluster` — worker processes on one Postgres (a throwaway `postgres:16` container, or `NOETA_TEST_POSTGRES_DSN`) under random SIGKILL / SIGSTOP with a scripted provider (`tests/cluster`); a known gap is an `xfail(strict=True)` there; `NOETA_CLUSTER_SEED` replays a run; never part of `check`
+- check: `make check` — ruff, mypy --strict, `scripts/lint-naming.py`, `scripts/lint-layout.py` (placement), `lint-imports` (layering), pytest with coverage ≥ 85, `make example` (the example plugins), `scripts/check-docs.sh`
+- docs: `make docs` — the docs site (VitePress in `docs/`, diagrams in `docs/diagrams/`, `npm run diagrams` restyles them); needs node, never part of `check`; `make docs-dev` previews it
+- frontends: `make frontends` — each front end's own checks (`web/`: npm typecheck, vitest, Playwright against a real `noeta serve` on a scripted provider); needs node and a browser, never part of `check`
+- release: tag push per `docs/releasing.md` — approval gate
+
+## Gates
+
+- Automated gates (required for done): `make check`. CI's test job runs the same target; CI-only on top: the Postgres parameters of the store contract tests (`NOETA_TEST_POSTGRES_DSN`), the Python 3.11 / 3.12 / 3.13 matrix, and the `cluster` job (`make cluster` against a Postgres service container).
+- `make check` can't judge model-facing prompt text or provider wire behavior. A change there also runs `make eval` (no scenario may regress; re-record the baseline when a scenario changes) and the relevant `make e2e` tests.
+- Approval gates (the maintainer signs off before running): release, data migration or deletion on a host's store.
+
+## Engineering constraints
+
+- Feature work changes behavior; maintenance work changes structure. Never mix them in one diff.
+- Prefer existing patterns in the repo, keep changes focused, and avoid unrelated refactors.
+- Architecturally, prefer deep modules: a small interface hiding a substantial implementation.
+- The interface is the test surface; don't introduce a seam without a real need to substitute the implementation.
+- Put new code where `CONTEXT.md`: Where code goes says, and respect the layering (`CONTEXT.md`: Layers): the kernel carries no capability; a plugin imports only `noeta.core` and `noeta.toolkit`. `lint-imports` and `scripts/lint-layout.py` enforce it.
+- Name things for what they do, never a metaphor — in code, doc terms, and file slugs alike.
+- Run verification matched to the risk; if you can't verify, say why.
+
+## Release
+
+- A merged behavior change to `noeta/` should be followed by a release; the published package must not lag `main`.
+- Bumps are patch by default — minor/major is the maintainer's explicit call.
+- Follow `docs/releasing.md`. Human sign-off = pushing the `vX.Y.Z` tag.
+
+## Maintenance
+
+- After a large feature merges, run a scoped gc over the changed area; periodically run a global gc — both per `docs/gc.md`.
+- When `make check` prints `gc due`, finish the task first, then tell the user and offer a scoped gc.
+- Every gc change leaves behavior unchanged; never mix gc into a feature diff.