matra 0.1.0__tar.gz

matra-0.1.0/.editorconfig

@@ -0,0 +1,35 @@
+# EditorConfig — https://editorconfig.org
+#
+# Universal editor defaults so any editor that supports the spec gets
+# the same charset, line endings, indentation, and trailing-whitespace
+# discipline as the rest of the toolchain (rustfmt, mypy, ruff).
+
+root = true
+
+[*]
+charset = utf-8
+end_of_line = lf
+insert_final_newline = true
+trim_trailing_whitespace = true
+indent_style = space
+indent_size = 4
+
+[*.{rs,toml}]
+indent_size = 4
+
+[*.{py,pyi}]
+indent_size = 4
+
+[*.{yml,yaml}]
+indent_size = 2
+
+[*.{md,markdown}]
+# Trailing whitespace is significant in markdown (two-space hard breaks).
+trim_trailing_whitespace = false
+indent_size = 2
+
+[Makefile]
+indent_style = tab
+
+[justfile]
+indent_size = 4

matra-0.1.0/.github/CODEOWNERS

@@ -0,0 +1,64 @@
+# CODEOWNERS for matra — change-gate protection on the load-bearing surfaces.
+#
+# GitHub uses this file to automatically request review from the listed
+# owner(s) when a PR touches a matching path. Today's role: ensure the
+# maintainer reviews any change to the docsite structure, CI workflows,
+# release scripts, ADRs, and the public manifest before merge. Future:
+# when contributors join, the path list stays the same but the owners
+# scale.
+#
+# Pattern syntax follows GitHub's CODEOWNERS spec.
+
+# Public manifest and version pins — every change here ripples through
+# crates.io, PyPI, and the supply chain.
+/Cargo.toml          @yzavyas
+/Cargo.lock          @yzavyas
+/pyproject.toml      @yzavyas
+
+# Docsite structure — SUMMARY.md is the navigation tree; book.toml owns
+# the build config; mermaid runtime is the bundled asset. Drift here is
+# silent and high-impact.
+/book/src/SUMMARY.md       @yzavyas
+/book/book.toml            @yzavyas
+/book/mermaid-init.js      @yzavyas
+/book/mermaid.min.js       @yzavyas
+
+# CI workflows — change to triggers, permissions, or pinned action SHAs
+# affects every subsequent PR.
+/.github/workflows/        @yzavyas
+
+# Release machinery — irreversible operations live here. Per the
+# durable per-publish approval rule (`memory/feedback_no_publish.md`),
+# every change to publish.yml, changelog-release.sh, the release recipe
+# in the justfile, or the supply-chain config gets explicit review.
+/justfile                              @yzavyas
+/scripts/changelog-release.sh          @yzavyas
+/scripts/check-boundaries.sh           @yzavyas
+/scripts/check-docsite-floor.sh        @yzavyas
+/scripts/install-hooks.sh              @yzavyas
+/scripts/pre-commit-hook.sh            @yzavyas
+/deny.toml                             @yzavyas
+
+# Architectural decisions — ADRs are the durable record. Anything in
+# docs/decisions/ should be reviewed for ADR-template compliance and
+# for ADR-supersede chain integrity.
+/docs/decisions/         @yzavyas
+
+# Hex boundary critical files — any change to domain.rs, the port
+# modules, or the composition root ripples through every adapter and
+# every consumer. The boundary-check script catches violations
+# mechanically; CODEOWNERS adds human review on top.
+/src/domain.rs           @yzavyas
+/src/lib.rs              @yzavyas
+/src/source/mod.rs       @yzavyas
+/src/decompose/mod.rs    @yzavyas
+/src/nlp/mod.rs          @yzavyas
+
+# The constitution. CLAUDE.md is loaded as agent context; CONTRIBUTING.md
+# is the human contributor's first stop; the collaboration model is the
+# exemplar document. None should drift without review.
+/CLAUDE.md                       @yzavyas
+/CONTRIBUTING.md                 @yzavyas
+/docs/collaboration-model.md     @yzavyas
+/README.md                       @yzavyas
+/CHANGELOG.md                    @yzavyas

matra-0.1.0/.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,39 @@
+---
+name: Bug report
+about: Something does not work the way the docs say it should
+title: "bug: "
+labels: ["type:bug", "status:triage"]
+---
+
+## What happened
+
+<!-- The unexpected behavior, in one or two sentences. -->
+
+## What you expected
+
+<!-- The behavior the docs / API surface implied. -->
+
+## Reproduction
+
+<!-- Minimal code or input that demonstrates the bug. The shorter, the better. -->
+
+```rust
+// or shell, or python — whatever reproduces it
+```
+
+## Environment
+
+- matra version (or git SHA): 
+- Rust version (`rustc --version`): 
+- OS / arch: 
+- Features enabled (`udpipe`, `python`, etc.): 
+
+## Logs / errors
+
+<!-- Stack traces, panic output, or error messages. Trim to the relevant frames. -->
+
+## Have you checked
+
+- [ ] The CHANGELOG.md for a known limitation or pending fix
+- [ ] Existing issues with the `type:bug` label
+- [ ] The relevant section of `.claude/arch/` for intended behavior

matra-0.1.0/.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,8 @@
+blank_issues_enabled: false
+contact_links:
+  - name: Security report
+    url: https://github.com/mox-labs/matra/security/advisories/new
+    about: Report a vulnerability privately. Do not file a public issue.
+  - name: Discussion
+    url: https://github.com/mox-labs/matra/discussions
+    about: Open-ended questions, design ideas, RFCs, or share what you built.

matra-0.1.0/.github/ISSUE_TEMPLATE/decision_record.md

@@ -0,0 +1,44 @@
+---
+name: Decision record
+about: Surface an architectural decision that needs deliberation before code moves
+title: "decision: "
+labels: ["type:decision", "status:open"]
+---
+
+## Context
+
+<!-- What is the situation that demands a decision? What forces are in tension? -->
+
+## Options under consideration
+
+<!-- Two or more concrete options. Each gets a name and a short description. -->
+
+### Option A: ...
+
+### Option B: ...
+
+### Option C: ...
+
+## Tradeoffs
+
+<!-- Per option: what does it buy, what does it cost, what does it foreclose? -->
+
+| Option | Reversibility | Surface impact | Ops cost | Notes |
+|--------|---------------|----------------|----------|-------|
+| A      |               |                |          |       |
+| B      |               |                |          |       |
+
+## What I'd do (and why)
+
+<!-- The author's recommendation, with reasoning. Not the final answer; the
+     starting point for the deliberation. -->
+
+## What success looks like
+
+<!-- How would we know the decision was right? What would a falsifying outcome
+     look like? -->
+
+## Outcome
+
+<!-- Filled in when the decision is made, before this issue closes. Links to
+     the resulting PR(s) and the ADR file under docs/decisions/. -->

matra-0.1.0/.github/ISSUE_TEMPLATE/feature_request.md

@@ -0,0 +1,39 @@
+---
+name: Feature request
+about: Propose a new capability, an extension, or a behavior change
+title: "feat: "
+labels: ["type:feature", "status:triage"]
+---
+
+## What you want to do
+
+<!-- The use case in one paragraph. Concrete: what input, what output. -->
+
+## Why matra should have it
+
+<!-- Is this part of matra's substrate role, or does it belong in a downstream
+     consumer? See book/src/architecture/design.md for the boundary. -->
+
+## Proposed shape
+
+<!-- API sketch, function signatures, types. Optional but helpful. -->
+
+```rust
+// API sketch
+```
+
+## Alternatives you considered
+
+<!-- Other ways to solve the same problem. Explain why they fall short. -->
+
+## Scope
+
+- [ ] Pure addition (non-breaking)
+- [ ] Modifies existing API (breaking)
+- [ ] Requires a new feature flag
+- [ ] Requires a new dependency
+
+## Have you checked
+
+- [ ] The iteration plan under `book/src/plans/` to see if this is already planned
+- [ ] Existing issues / discussions for prior art

matra-0.1.0/.github/dependabot.yml

@@ -0,0 +1,59 @@
+version: 2
+
+updates:
+  # Rust dependencies (Cargo.toml, Cargo.lock).
+  - package-ecosystem: cargo
+    directory: "/"
+    schedule:
+      interval: weekly
+      day: monday
+    open-pull-requests-limit: 5
+    labels:
+      - "area:deps"
+      - "type:chore"
+    groups:
+      # Group minor + patch updates into a single PR to reduce noise.
+      # Major version bumps still open their own PRs (reviewed individually).
+      cargo-minor-patch:
+        update-types:
+          - minor
+          - patch
+    commit-message:
+      prefix: "chore(deps)"
+      include: scope
+
+  # GitHub Actions workflows.
+  - package-ecosystem: github-actions
+    directory: "/"
+    schedule:
+      interval: weekly
+      day: monday
+    open-pull-requests-limit: 3
+    labels:
+      - "area:ci"
+      - "type:chore"
+    groups:
+      actions-minor-patch:
+        update-types:
+          - minor
+          - patch
+    commit-message:
+      prefix: "chore(ci)"
+
+  # Python dependencies in pyproject.toml.
+  - package-ecosystem: pip
+    directory: "/"
+    schedule:
+      interval: weekly
+      day: monday
+    open-pull-requests-limit: 3
+    labels:
+      - "area:python"
+      - "type:chore"
+    groups:
+      pip-minor-patch:
+        update-types:
+          - minor
+          - patch
+    commit-message:
+      prefix: "chore(deps)"

matra-0.1.0/.github/pull_request_template.md

@@ -0,0 +1,41 @@
+<!--
+PR template for matra. Keep it tight; reviewers should see what changed
+and why in under 60 seconds.
+-->
+
+## Summary
+
+<!-- One paragraph: what changed, what problem this solves. -->
+
+## Why
+
+<!-- The mental model. The reason a future reader (or you in 6 months) needs.
+     Skip if the change is purely mechanical (rename, format, lint fix). -->
+
+## Test plan
+
+<!-- Concrete: which gates were run, what new tests exist, what was manually
+     exercised. The acceptance criterion for this PR. -->
+
+- [ ] `just check` (full local CI gate)
+- [ ] New tests added for new behavior, regressions, or invariants
+- [ ] CHANGELOG.md `[Unreleased]` updated
+- [ ] If the change is architectural / breaking / security-relevant: a
+      Highlight paragraph added under `[Unreleased]`
+
+## Type of change
+
+- [ ] Bug fix (non-breaking)
+- [ ] Feature (non-breaking)
+- [ ] Breaking change (API surface, behavior, error shape)
+- [ ] Documentation only
+- [ ] Tooling / CI / process
+
+## Linked issues
+
+<!-- "Closes #N" / "Related to #N". -->
+
+## Notes for the reviewer
+
+<!-- Anything specific the reviewer should look at: a tricky boundary
+     case, a tradeoff, a follow-up that is intentionally deferred. -->

matra-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,183 @@
+name: CI
+
+on:
+  push:
+    branches: [main, alpha]
+  pull_request:
+    branches: [main, alpha]
+
+# Principle of least privilege at the workflow level. Individual jobs
+# escalate only what they need via a per-job `permissions:` block.
+permissions: read-all
+
+env:
+  CARGO_TERM_COLOR: always
+  RUSTFLAGS: -Dwarnings
+
+jobs:
+  rust:
+    name: Rust ${{ matrix.os }} / ${{ matrix.features }}
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, macos-latest]
+        include:
+          - features: default
+            flags: ""
+          - features: no-default-features
+            flags: "--no-default-features"
+    steps:
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd  # v6.0.2
+        with:
+          persist-credentials: false
+
+      - name: Install Rust toolchain
+        uses: dtolnay/rust-toolchain@efa25f7f19611383d5b0ccf2d1c8914531636bf9  # master (no tagged release; pinned to known-good commit)
+        with:
+          toolchain: stable
+          components: clippy, rustfmt
+
+      - uses: Swatinem/rust-cache@779680da715d629ac1d338a641029a2f4372abb5  # v2
+
+      - name: cargo fmt --check
+        if: matrix.features == 'default' && matrix.os == 'ubuntu-latest'
+        run: cargo fmt --all -- --check
+
+      - name: cargo check
+        run: cargo check --all-targets ${{ matrix.flags }}
+
+      - name: cargo clippy
+        run: cargo clippy --all-targets ${{ matrix.flags }} -- -D warnings
+
+      - name: cargo test (lib + doc)
+        run: cargo test ${{ matrix.flags }}
+
+  msrv:
+    name: MSRV (Rust 1.85)
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd  # v6.0.2
+        with:
+          persist-credentials: false
+      - uses: dtolnay/rust-toolchain@efa25f7f19611383d5b0ccf2d1c8914531636bf9  # master
+        with:
+          toolchain: "1.85"
+      - uses: Swatinem/rust-cache@779680da715d629ac1d338a641029a2f4372abb5  # v2
+      - name: cargo check (MSRV, all features)
+        run: cargo check --all-targets --all-features
+      - name: cargo check (MSRV, no default features)
+        run: cargo check --all-targets --no-default-features
+
+  deny:
+    name: cargo-deny
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd  # v6.0.2
+        with:
+          persist-credentials: false
+      - uses: EmbarkStudios/cargo-deny-action@3fd3802e88374d3fe9159b834c7714ec57d6c979  # v2
+        with:
+          command: check
+          arguments: --all-features
+
+  semver:
+    name: cargo-semver-checks
+    runs-on: ubuntu-latest
+    # PR-only — we don't gate main on this (the baseline is the published version).
+    # `continue-on-error: true` because matra has not yet been published to
+    # crates.io. The action errors with "matra not found in registry" until
+    # there is a published baseline to compare against. Once the first
+    # publish happens, drop continue-on-error so PRs that break semver fail.
+    if: github.event_name == 'pull_request'
+    continue-on-error: true
+    steps:
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd  # v6.0.2
+        with:
+          persist-credentials: false
+      - uses: dtolnay/rust-toolchain@efa25f7f19611383d5b0ccf2d1c8914531636bf9  # master
+        with:
+          toolchain: stable
+      - uses: Swatinem/rust-cache@779680da715d629ac1d338a641029a2f4372abb5  # v2
+      - uses: obi1kenobi/cargo-semver-checks-action@6b69fcf40e9b5fb17adeb57e4b6ecd020649a239  # v2.9
+        with:
+          feature-group: all-features
+
+  docs:
+    name: rustdoc
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd  # v6.0.2
+        with:
+          persist-credentials: false
+      - uses: dtolnay/rust-toolchain@efa25f7f19611383d5b0ccf2d1c8914531636bf9  # master
+        with:
+          toolchain: stable
+      - uses: Swatinem/rust-cache@779680da715d629ac1d338a641029a2f4372abb5  # v2
+      - name: cargo doc
+        env:
+          RUSTDOCFLAGS: -Dwarnings
+        run: cargo doc --no-deps --all-features
+
+  python:
+    name: Python wheel (${{ matrix.os }} / ${{ matrix.python-version }})
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, macos-latest]
+        python-version: ["3.12"]
+    steps:
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd  # v6.0.2
+        with:
+          persist-credentials: false
+      - uses: dtolnay/rust-toolchain@efa25f7f19611383d5b0ccf2d1c8914531636bf9  # master
+        with:
+          toolchain: stable
+      - uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405  # v6.2.0
+        with:
+          python-version: ${{ matrix.python-version }}
+      - uses: Swatinem/rust-cache@779680da715d629ac1d338a641029a2f4372abb5  # v2
+      - name: Install uv
+        run: python -m pip install --upgrade uv
+      - name: Install maturin
+        run: uv pip install --system maturin
+      - name: Build wheel
+        run: maturin build --release --out dist
+      - name: Install and import
+        shell: bash
+        run: |
+          uv pip install --system dist/matra-*.whl
+          python -c "from matra import Matra; print('ok')"
+
+  pytype:
+    name: Python type-check (mypy)
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd  # v6.0.2
+        with:
+          persist-credentials: false
+      - uses: dtolnay/rust-toolchain@efa25f7f19611383d5b0ccf2d1c8914531636bf9  # master
+        with:
+          toolchain: stable
+      - uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405  # v6.2.0
+        with:
+          python-version: "3.12"
+      - uses: Swatinem/rust-cache@779680da715d629ac1d338a641029a2f4372abb5  # v2
+      - name: Create venv (maturin develop requires VIRTUAL_ENV)
+        run: python -m venv .venv
+      - name: Install maturin + mypy in venv
+        run: |
+          . .venv/bin/activate
+          python -m pip install --upgrade uv
+          # No --system: install into the activated venv, where the
+          # mypy step below runs. Newer uv treats --system literally.
+          uv pip install maturin "mypy>=1.10" click rich
+      - name: Build and install matra in venv (so the _core stub resolves)
+        run: |
+          . .venv/bin/activate
+          maturin develop --features "python,udpipe"
+      - name: mypy
+        run: |
+          . .venv/bin/activate
+          python -m mypy

matra-0.1.0/.github/workflows/claude-code-review.yml

@@ -0,0 +1,47 @@
+name: Claude Code Review
+
+on:
+  pull_request:
+    types: [opened, synchronize, ready_for_review, reopened]
+    # Optional: Only run on specific file changes
+    # paths:
+    #   - "src/**/*.ts"
+    #   - "src/**/*.tsx"
+    #   - "src/**/*.js"
+    #   - "src/**/*.jsx"
+
+jobs:
+  claude-review:
+    # Optional: Filter by PR author
+    # if: |
+    #   github.event.pull_request.user.login == 'external-contributor' ||
+    #   github.event.pull_request.user.login == 'new-developer' ||
+    #   github.event.pull_request.author_association == 'FIRST_TIME_CONTRIBUTOR'
+
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      pull-requests: write
+      issues: read
+      id-token: write
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd  # v6.0.2
+        with:
+          fetch-depth: 0
+          persist-credentials: false
+
+      - name: Run Claude Code Review
+        id: claude-review
+        uses: anthropics/claude-code-action@3f854a8fb5146b39d5cbf8b57f70d80810e1366f  # v1
+        with:
+          claude_code_oauth_token: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}
+          # Project-specific review: the pr-review skill in this repo
+          # carries the gates (boundary rules, pipeline laws, substrate
+          # discipline, FFI criterion). The generic code-review plugin
+          # is deliberately not used.
+          prompt: 'Use the pr-review skill to review pull request #${{ github.event.pull_request.number }} in ${{ github.repository }}, and post the review as a PR comment per the skill output contract.'
+          claude_args: '--model claude-fable-5'
+          # See https://github.com/anthropics/claude-code-action/blob/main/docs/usage.md
+

matra-0.1.0/.github/workflows/claude.yml

@@ -0,0 +1,50 @@
+name: Claude Code
+
+on:
+  issue_comment:
+    types: [created]
+  pull_request_review_comment:
+    types: [created]
+  issues:
+    types: [opened, assigned]
+  pull_request_review:
+    types: [submitted]
+
+jobs:
+  claude:
+    if: |
+      (github.event_name == 'issue_comment' && contains(github.event.comment.body, '@claude')) ||
+      (github.event_name == 'pull_request_review_comment' && contains(github.event.comment.body, '@claude')) ||
+      (github.event_name == 'pull_request_review' && contains(github.event.review.body, '@claude')) ||
+      (github.event_name == 'issues' && (contains(github.event.issue.body, '@claude') || contains(github.event.issue.title, '@claude')))
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      pull-requests: read
+      issues: read
+      id-token: write
+      actions: read # Required for Claude to read CI results on PRs
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 1
+
+      - name: Run Claude Code
+        id: claude
+        uses: anthropics/claude-code-action@v1
+        with:
+          claude_code_oauth_token: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}
+
+          # This is an optional setting that allows Claude to read CI results on PRs
+          additional_permissions: |
+            actions: read
+
+          # Optional: Give a custom prompt to Claude. If this is not specified, Claude will perform the instructions specified in the comment that tagged it.
+          # prompt: 'Update the pull request description to include a summary of changes.'
+
+          # Optional: Add claude_args to customize behavior and configuration
+          # See https://github.com/anthropics/claude-code-action/blob/main/docs/usage.md
+          # or https://code.claude.com/docs/en/cli-reference for available options
+          # claude_args: '--allowed-tools Bash(gh pr *)'
+

matra-0.1.0/.github/workflows/codeql.yml

@@ -0,0 +1,54 @@
+name: CodeQL
+
+# GitHub's static analysis for security issues. Custom workflow (vs. the
+# "default setup" UI option) lets us pin the action to a SHA and integrate
+# with Scorecard.
+#
+# IMPORTANT: before this workflow can run, the repo's CodeQL "default setup"
+# must be disabled in Settings -> Code security -> Code scanning. Otherwise
+# GitHub rejects the custom workflow with "default setup is already
+# enabled". See docs/decisions/0005-supply-chain-hardening.md.
+
+on:
+  push:
+    branches: [main, alpha]
+  pull_request:
+    branches: [main, alpha]
+  schedule:
+    - cron: "12 3 * * 2"   # Tuesdays 03:12 UTC
+
+permissions: read-all
+
+jobs:
+  analyze:
+    name: Analyze (${{ matrix.language }})
+    runs-on: ubuntu-latest
+    permissions:
+      security-events: write
+      packages: read
+      contents: read
+
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - language: rust
+            build-mode: none
+          - language: python
+            build-mode: none
+
+    steps:
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd  # v6.0.2
+        with:
+          persist-credentials: false
+
+      - name: Initialize CodeQL
+        uses: github/codeql-action/init@0d579ffd059c29b07949a3cce3983f0780820c98  # v4
+        with:
+          languages: ${{ matrix.language }}
+          build-mode: ${{ matrix.build-mode }}
+
+      - name: Analyze
+        uses: github/codeql-action/analyze@0d579ffd059c29b07949a3cce3983f0780820c98  # v4
+        with:
+          category: "/language:${{ matrix.language }}"