strictspec 0.1.0__tar.gz

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

@@ -0,0 +1,33 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+  workflow_dispatch:
+
+# Per-SHA group: re-runs of the same commit dedupe, but a new commit never
+# cancels an earlier commit's in-flight run (release CI conclusions stay intact).
+concurrency:
+  group: ${{ github.workflow_ref }}-${{ github.sha }}
+  cancel-in-progress: true
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        # requires-python: >= 3.11
+        python-version: ["3.12", "3.13", "3.14"]
+    steps:
+      - uses: actions/checkout@v6
+      - uses: astral-sh/setup-uv@v7
+      - run: uv python install ${{ matrix.python-version }}
+      - run: uv sync --locked
+      - run: uv run python -c "import strictspec"
+      - name: Install gitleaks
+        run: |
+          GITLEAKS_VERSION=8.24.3
+          curl -sSfL "https://github.com/gitleaks/gitleaks/releases/download/v${GITLEAKS_VERSION}/gitleaks_${GITLEAKS_VERSION}_linux_x64.tar.gz" | tar xz -C /usr/local/bin gitleaks
+      - run: uv run pytest --rootdir .

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

@@ -0,0 +1,187 @@
+name: Publish
+on:
+  release:
+    types: [published]
+  workflow_dispatch:
+    inputs:
+      tag:
+        description: Release tag to publish (e.g. v1.2.3). Overrides the ref for
+          retry dispatch.
+        required: false
+        type: string
+
+# One publish run per tag: a workflow_dispatch retry at the same tag
+# queues behind the in-flight run instead of racing it. A publish is never
+# cancelled mid-flight.
+concurrency:
+  group: publish-${{ inputs.tag || github.ref_name }}
+  cancel-in-progress: false
+permissions:
+  contents: read
+  id-token: write
+jobs:
+  gate:
+    name: Gate on CI
+    runs-on: ubuntu-latest
+    permissions:
+      checks: read
+    env:
+      GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+      GATE_TIMEOUT_MINUTES: '20'
+      GATE_GRACE_MINUTES: '5'
+      GATE_POLL_SECONDS: '15'
+      GATE_MARKER_ATTEMPTS: '5'
+      GATE_MARKER_RETRY_SECONDS: '5'
+      CI_CHECK_REGEX: ^(test)( \(.*\))?$
+    steps:
+      - name: Wait for CI to succeed on the release commit
+        run: |
+          set -euo pipefail
+
+          # Commit resolution -- explicit marker-first order (never reads the release
+          # event payload; dispatch retries have none, so this path is uniform for
+          # release events and dispatch retries alike):
+          #   (1) Marker: rlsbl writes the exact commit CI ran on into the GitHub
+          #       Release body as a machine-parseable line of the form
+          #           <!-- rlsbl-ci-sha: <40-hex> -->
+          #       Prefer it when present -- it pins the precise commit and is immune to
+          #       ref races. A just-created release can lag on a GitHub API read replica
+          #       (the marker is written at release creation but may not be visible on
+          #       the first read), so RETRY the read GATE_MARKER_ATTEMPTS times,
+          #       GATE_MARKER_RETRY_SECONDS apart, before concluding it is absent. The
+          #       tag is inputs.tag (TAG_INPUT) when dispatched with an explicit
+          #       override, else GITHUB_REF_NAME (matches the router resolver).
+          #   (2) Fallback: older releases predate the marker, so fall back to
+          #       $GITHUB_SHA, the tag's commit for both release and dispatch-at-tag.
+          extract_ci_sha() {
+            # Emit the first rlsbl-ci-sha marker SHA found on stdin, if any.
+            sed -n 's/.*<!-- rlsbl-ci-sha: \([0-9a-f]\{40\}\) -->.*/\1/p' | head -n1
+          }
+          tag="${TAG_INPUT:-$GITHUB_REF_NAME}"
+          marker_attempts="${GATE_MARKER_ATTEMPTS:-5}"
+          marker_retry_seconds="${GATE_MARKER_RETRY_SECONDS:-5}"
+          sha=""
+          attempt=1
+          while [ "$attempt" -le "$marker_attempts" ]; do
+            if body="$(gh release view "$tag" --json body --jq .body 2>/dev/null)"; then
+              sha="$(printf '%s\n' "$body" | extract_ci_sha)"
+            fi
+            if [ -n "$sha" ]; then
+              break
+            fi
+            if [ "$attempt" -lt "$marker_attempts" ]; then
+              echo "Publish gate: rlsbl-ci-sha marker not yet visible in the '$tag' release body (attempt $attempt/$marker_attempts); retrying in ${marker_retry_seconds}s..."
+              sleep "$marker_retry_seconds"
+            fi
+            attempt=$(( attempt + 1 ))
+          done
+          if [ -n "$sha" ]; then
+            echo "Publish gate: resolved release commit from rlsbl-ci-sha marker in the '$tag' release body."
+          else
+            sha="$GITHUB_SHA"
+            echo "Publish gate: no rlsbl-ci-sha marker after $marker_attempts attempt(s) on the '$tag' release body; falling back to \$GITHUB_SHA."
+          fi
+          echo "Publish gate: waiting for CI on $GITHUB_REF_NAME (commit $sha)"
+          echo "Check-run name filter: $CI_CHECK_REGEX"
+          # Timeout, grace window, and poll interval come from the job env above;
+          # edit them there if this repository's CI needs different limits.
+
+          now() { date +%s; }
+          start="$(now)"
+          deadline=$(( start + GATE_TIMEOUT_MINUTES * 60 ))
+          grace_deadline=$(( start + GATE_GRACE_MINUTES * 60 ))
+
+          while :; do
+            if ! resp="$(gh api --paginate "repos/$GITHUB_REPOSITORY/commits/$sha/check-runs?per_page=100")"; then
+              echo "Checks API request failed; retrying in ${GATE_POLL_SECONDS}s..."
+              sleep "$GATE_POLL_SECONDS"
+              continue
+            fi
+            # Match this project's CI check runs by name; exclude check runs that
+            # belong to THIS workflow run (the gate itself and the queued publish
+            # jobs would otherwise deadlock the poll loop).
+            # A retried CI run creates a BRAND-NEW check-run with the same name as the
+            # old one, so a stale failure would block the gate forever. Project id and
+            # started_at, then reduce to the latest check-run per name (max started_at,
+            # numeric id as tiebreak for retries within the same second) BEFORE the
+            # pending / not-success logic runs. This way the newest run decides: still
+            # running -> wait; genuinely red -> hard fail.
+            runs="$(jq -s --arg re "$CI_CHECK_REGEX" --arg run_id "$GITHUB_RUN_ID" '
+              [ .[].check_runs[]
+                | select(.name | test($re))
+                | select((.details_url // "") | contains("/actions/runs/" + $run_id + "/") | not)
+                | {name, status, conclusion, id, started_at} ]
+              | group_by(.name)
+              | map(sort_by(.started_at, .id) | last)' <<< "$resp")"
+            total="$(jq 'length' <<< "$runs")"
+
+            if [ "$total" -eq 0 ]; then
+              if [ "$(now)" -ge "$grace_deadline" ]; then
+                echo "::error::Publish gate: no CI check runs matching $CI_CHECK_REGEX appeared on $sha within $GATE_GRACE_MINUTES minutes."
+                echo "A scaffolded repository always has a CI workflow, so the release commit must produce CI check runs."
+                echo "If CI jobs were renamed, update CI_CHECK_REGEX in this workflow's gate job to match the new names."
+                exit 1
+              fi
+              echo "No matching CI check runs yet; retrying in ${GATE_POLL_SECONDS}s..."
+              sleep "$GATE_POLL_SECONDS"
+              continue
+            fi
+
+            pending="$(jq '[ .[] | select(.status != "completed") ] | length' <<< "$runs")"
+            if [ "$pending" -gt 0 ]; then
+              if [ "$(now)" -ge "$deadline" ]; then
+                echo "::error::Publish gate: timed out after $GATE_TIMEOUT_MINUTES minutes waiting for CI to complete on $sha."
+                jq -r '.[] | "  \(.name): status=\(.status) conclusion=\(.conclusion // "none")"' <<< "$runs"
+                exit 1
+              fi
+              echo "$pending of $total matching CI check runs still running; retrying in ${GATE_POLL_SECONDS}s..."
+              sleep "$GATE_POLL_SECONDS"
+              continue
+            fi
+
+            not_success="$(jq '[ .[] | select(.conclusion != "success") ]' <<< "$runs")"
+            if [ "$(jq 'length' <<< "$not_success")" -gt 0 ]; then
+              echo "::error::Publish gate: CI did not pass on $sha -- refusing to publish."
+              jq -r '.[] | "  \(.name): \(.conclusion)"' <<< "$not_success"
+              while IFS= read -r conclusion; do
+                case "$conclusion" in
+                  failure|timed_out)
+                    echo "CI concluded '$conclusion' on the release commit. Fix the failure, re-run the CI workflow to green on this exact commit (gh run rerun <run-id>), then re-dispatch this publish workflow at the tag ref: gh workflow run <publish workflow> --ref $GITHUB_REF_NAME"
+                    ;;
+                  cancelled)
+                    echo "A CI check run was CANCELLED. A cancelled run proves nothing about the commit, so the gate treats it as a hard failure instead of waiting for a conclusion that will never come. Re-run the cancelled CI workflow (gh run rerun <run-id>), then re-dispatch this publish workflow at the tag ref."
+                    ;;
+                  skipped)
+                    echo "A CI check run matching the filter was SKIPPED. The gate cannot treat a skipped check as passing: this project's own CI must actually run on the release commit. Check paths filters and job conditions, re-run CI on this commit, then re-dispatch this publish workflow at the tag ref."
+                    ;;
+                  *)
+                    echo "CI check concluded '$conclusion' (not success). The gate only proceeds when every matching check concluded success."
+                    ;;
+                esac
+              done <<< "$(jq -r '.[].conclusion' <<< "$not_success" | sort -u)"
+              exit 1
+            fi
+
+            echo "Publish gate: all $total matching CI check runs succeeded."
+            jq -r '.[] | "  \(.name): \(.conclusion)"' <<< "$runs"
+            exit 0
+          done
+  pypi:
+    needs: gate
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          ref: ${{ inputs.tag || github.event.release.tag_name }}
+      - uses: astral-sh/setup-uv@v7
+      - name: Install gitleaks
+        run: |
+          GITLEAKS_VERSION=8.24.3
+          curl -sSfL "https://github.com/gitleaks/gitleaks/releases/download/v${GITLEAKS_VERSION}/gitleaks_${GITLEAKS_VERSION}_linux_x64.tar.gz" | tar xz -C /usr/local/bin gitleaks
+      - run: uv build --out-dir dist
+      - name: Scan artifacts for secrets
+        run: |
+          gitleaks dir dist/
+      - uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          skip-existing: true

strictspec-0.1.0/.gitignore

@@ -0,0 +1,23 @@
+dist/
+__pycache__/
+*.pyc
+*.egg-info/
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+.venv/
+
+node_modules/
+*.log
+.DS_Store
+coverage/
+build/
+target/
+.rlsbl-notes-*.tmp
+.rlsbl/lock
+.rlsbl-monorepo/lock
+.credentials.json
+.*-cache.json
+.env
+.env.local
+*.local-only

strictspec-0.1.0/.rlsbl/config.json

@@ -0,0 +1,13 @@
+{
+  "targets": [
+    "pypi"
+  ],
+  "publish_mode": "ci",
+  "pipelines": {
+    "pypi": {
+      "type": "pypi",
+      "target": "pypi",
+      "local": false
+    }
+  }
+}

strictspec-0.1.0/.rlsbl/lint/python.toml

@@ -0,0 +1,25 @@
+[forbidden-imports]
+modules = [
+    "argparse",
+    "click",
+    "typer",
+    "flask",
+    "fastapi",
+    "django",
+    "uvicorn",
+    "granian",
+    "starlette",
+    "tornado",
+    "bottle",
+]
+
+[stdout]
+enabled = true
+ignore = []
+
+[entry-point]
+enabled = true
+ignore = []
+
+[files]
+exclude = []

strictspec-0.1.0/.rlsbl/managed-files.json

@@ -0,0 +1,9 @@
+{
+  "version": 1,
+  "files": {
+    ".github/workflows/ci.yml": "71084265487b6ac5bbe6ce9fc2dabd5598db35afae5eaba0cb64c36b1131f0d1",
+    ".github/workflows/publish.yml": "9bc0b409f8c5c2a3c5795a3e7c66095b9479c1a03fb41250ff0461e1221b54f2",
+    ".gitignore": "89e4405f5bf2af8e5c1165bf3cc1e5592f8b12e9c21b3aea9e4f05077a23b1f2",
+    ".rlsbl/lint/python.toml": "9cfbcef2e010d5fad243437bf2fd8df54a1fae70ee0762f9d11da70fe207501c"
+  }
+}

strictspec-0.1.0/DESIGN.md

@@ -0,0 +1,81 @@
+# python/ — Python Runtime Library and PyPI Releasable
+
+NOT the toolchain (that's Go). Runtime support for generated Python code, published to PyPI as
+`strictspec`. There is NO separate binary package: the former `-bin` wrapper is eliminated
+(decision 31). The PyPI `strictspec` wheel (stays `py3-none-any`) exposes a `strictspec`
+console script that lazy-downloads the exact-version Go binary from the GitHub Release — with
+SHA-256 checksum verification — into a platform cache on FIRST CLI INVOCATION. Library-only
+installs (importing the runtime without ever invoking the CLI) do zero network access. The
+download shim is built on rlsbl's first-party "launcher" artifact mechanism (checksum-verifying
+templates). Runtime package version = strictspec release version, so the lazy download and the
+exact version-pairing rule agree by construction.
+
+## Generated-code style
+
+Frozen dataclasses + explicit generated checks + generated `with_*` copy helpers. pydantic and
+msgspec are out: two-phase domain checks require partial-subtree binding, and deterministic
+generated output requires full control of every emitted line. Zero third-party runtime deps in
+generated code; one emitter architecture across all three languages. Generated checks always
+hard-error on unknown keys — a language invariant, not a declared policy and never a library
+default. Freezing is shallow-plus-generated-immutability (nested edits go through `with_*`
+helpers). Generated files land chmod 444 in consumer repos, carry a `# ruff: noqa` header plus
+the generated-by header, and are formatted by the generator's own canonical emitter — no
+external formatter is ever involved, and consumers never hand-silence linters on generated
+paths.
+
+## Entry points (per the Generated API Contract)
+
+1. Raw text/bytes: this runtime's reader parses losslessly (lexeme classification per the
+   primitives appendix; duplicate keys surfaced via object_pairs_hook and hard-errored;
+   int64/float64 overflow and number-scalar unrepresentable lexemes hard-errored) into tagged
+   document-model values, then validates.
+2. Tagged document-model values: from the reader or from generated typed constructors (where
+   integer/float/number/datetime is explicit in the type). Raw untagged dicts are NOT accepted
+   as validation input — ambiguity never enters the model. This serves in-memory
+   mutate-then-validate consumers (PixelWeaver's server validates dicts built by MCP mutations
+   today; post-migration it builds tagged values via constructors and `with_*` helpers).
+
+Result type: (typed value | None) x ordered diagnostics; every diagnostic is an error (no
+severity field, no warnings); the assert-style wrapper raises on any diagnostic. Version gate
+first, with the structured remediation payload.
+
+## Contents
+
+- Diagnostics: the spec/ error model (code, path, message, expected/got, suggestion, optional
+  position — NO severity), terminal + JSON renderers emitting from the spec-pinned message
+  templates, did-you-mean per appendix item 7 (cross-target normative — codes, paths, AND
+  rendered message text are the conformance surface), the constructor for consumer-prefixed
+  codes (used by consumer-native checks downstream of validation).
+- Tagged document model: lexeme-retaining values; JSON reader (ordered, duplicate-rejecting),
+  TOML round-trip via tomlkit (within-backend fixpoint; never byte-identical to the Go
+  substrate), JSONL streamed line-by-line (memory bounded by the largest line, not the file;
+  all-errors-in-one-pass applies per line; positions are byte offsets; LF-only; per-line
+  positional errors), O_APPEND single-writer appends, temp+rename rewrites, immutability
+  helpers. Datetime scalars per appendix item 11 (TOML natives; RFC 3339 strings in JSON;
+  binds datetime/date/time with kind guards). Write side per the canonical-serialization
+  appendix: untouched values keep their lexemes; constructed floats render with float lexemes;
+  the write path REFUSES non-current format_version serialization (producer-current-only).
+  Validating a TOML-syntax document against a schema in which a nullable union is reachable =
+  canonical hard error.
+- The inline version-gate helper (three-message pattern + structured remediation payload).
+- Scalar guards per spec/ (number scalar with unrepresentable-lexeme rejection; datetime
+  kinds; integral-float, bool-not-int, non-finite).
+- The CONSTRAINT ENGINE: the ported cross-document vocabulary evaluator plus the Python
+  implementations of the evidence resolvers (filesystem, sibling documents, git where
+  available). There is no consumer registration surface — vocabulary checks are
+  schema-declared and portable; the bespoke tail is consumer-native code over typed values,
+  run by the consumer after validation. A resolver this environment cannot satisfy is a hard
+  error naming the resolver.
+- Boundary-checkpoint support: generated ingest write-doors and egress wrappers invoke the
+  migration engine via the packaged CLI (the engine itself never lives in this runtime); the
+  wrappers are generated only for manifest-declared stores/channels.
+
+## Invariants
+
+- No toolchain logic: no schema parsing, no generation, no migration engine (checkpoints
+  delegate to the packaged CLI).
+- No lenient modes; loading and validation inseparable; discovery collects per-file errors and
+  fails loudly. No warnings anywhere.
+- Version pairing with generated code: exact match per release; dev builds pair only with
+  themselves. The pairing hard error is the intended surfacing of skew under always-latest
+  dependencies; remediation is regeneration, never pinning.

strictspec-0.1.0/LICENSE

@@ -0,0 +1,32 @@
+MIT License
+
+Copyright (c) 2026 S. M. Hosseini
+
+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.
+
+---
+
+Generated output.
+
+Code that the strictspec generator emits into a consumer's repository is
+unencumbered: no license obligation attaches to generated output. You may use,
+modify, and distribute strictspec-generated code without restriction and
+without any requirement to reproduce this license or the copyright notice
+above. This MIT license governs the strictspec toolchain and runtimes
+themselves, not the code they generate for you.

strictspec-0.1.0/PKG-INFO

@@ -0,0 +1,32 @@
+Metadata-Version: 2.4
+Name: strictspec
+Version: 0.1.0
+Summary: Strict multi-language schema toolchain for declarative spec files (Python runtime + CLI stub)
+Project-URL: Homepage, https://github.com/smm-h/strictspec
+Project-URL: Repository, https://github.com/smm-h/strictspec
+Author-email: "S. M. Hosseini" <m.hosseini@veliu.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: codegen,rlsbl,schema,strictspec,toml,validation
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.11
+Requires-Dist: tomlkit
+Description-Content-Type: text/markdown
+
+# strictspec (Python)
+
+Python runtime library and CLI stub for [strictspec](https://github.com/smm-h/strictspec),
+a strict multi-language schema toolchain for declarative spec files.
+
+This is a placeholder skeleton. The runtime (document I/O, diagnostics, tagged
+values, constraint engine) and the CLI launcher stub land in a later phase.
+
+## Development
+
+```bash
+uv sync
+uv run pytest
+```

strictspec-0.1.0/README.md

@@ -0,0 +1,14 @@
+# strictspec (Python)
+
+Python runtime library and CLI stub for [strictspec](https://github.com/smm-h/strictspec),
+a strict multi-language schema toolchain for declarative spec files.
+
+This is a placeholder skeleton. The runtime (document I/O, diagnostics, tagged
+values, constraint engine) and the CLI launcher stub land in a later phase.
+
+## Development
+
+```bash
+uv sync
+uv run pytest
+```

strictspec-0.1.0/pyproject.toml

@@ -0,0 +1,37 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "strictspec"
+version = "0.1.0"
+description = "Strict multi-language schema toolchain for declarative spec files (Python runtime + CLI stub)"
+readme = "README.md"
+requires-python = ">=3.11"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "S. M. Hosseini", email = "m.hosseini@veliu.com" }]
+keywords = ["strictspec", "schema", "codegen", "validation", "toml", "rlsbl"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "Programming Language :: Python :: 3",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+]
+dependencies = ["tomlkit"]
+
+[project.scripts]
+strictspec = "strictspec._launcher:main"
+
+[dependency-groups]
+dev = ["pytest"]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/strictspec"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+
+[project.urls]
+Homepage = "https://github.com/smm-h/strictspec"
+Repository = "https://github.com/smm-h/strictspec"

strictspec-0.1.0/scripts/conformance_adapter.py

@@ -0,0 +1,117 @@
+"""Conformance-adapter for the strictspec Python runtime.
+
+The Python-side invocation contract for the cross-target conformance harness's
+``python`` target. It reads a JSON request on stdin describing one fixture
+(schema path + input document + optional cross-document evidence), drives the
+PUBLIC Python runtime (``compile_embedded`` + ``Program.validate`` / the
+meta-schema reader for meta fixtures), and writes the observed outcome as JSON on
+stdout in the runner's expected shape::
+
+    {"valid": bool, "diagnostics": [{"code","path","message"}, ...]}
+
+This is the exact request/response contract the Go ``conformance-adapter`` speaks
+(go/cmd/conformance-adapter/main.go); byte-identical outcomes across targets are
+what the parity checker asserts. The harness prepares the Python environment once
+(uv) and invokes this script per fixture -- the strictcli conformance pattern:
+compile the schema once, feed the input document.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import sys
+
+import strictspec
+from strictspec import _doc, _render, _schema
+
+
+def _build_fileset(schema_path: str) -> tuple[dict[str, str], str]:
+    """Read every ``.toml`` in the schema's directory into an in-memory FileSet,
+    keyed by basename. This mirrors the Go adapter: imports reference sibling
+    files by bare filename, and the scalar manifest is a sibling ``.toml`` that
+    ``load_manifest_scalars_from`` merges across every file in the set.
+    """
+    directory = os.path.dirname(schema_path)
+    files: dict[str, str] = {}
+    for name in os.listdir(directory):
+        full = os.path.join(directory, name)
+        if os.path.isdir(full) or not name.endswith(".toml"):
+            continue
+        with open(full, encoding="utf-8") as f:
+            files[name] = f.read()
+    return files, os.path.basename(schema_path)
+
+
+def _read_input(req: dict) -> bytes:
+    inline = req.get("input_inline")
+    if inline:
+        return inline.encode("utf-8")
+    return open(req["input_path"], "rb").read()
+
+
+def _render_diags(diags: list) -> list[dict[str, str]]:
+    return [
+        {"code": d.code, "path": d.path.render(), "message": _render.render(d)}
+        for d in diags
+    ]
+
+
+def _meta_validate(req: dict) -> list[dict[str, str]]:
+    """Read the input file AS a schema/type-definition file and return the
+    meta-schema reader's authoring diagnostics (mirrors Go's metaValidate)."""
+    src = _read_input(req)
+    try:
+        d = _tomldoc_parse(src)
+    except _doc.ParseError as pe:
+        return _render_diags([strictspec._parse_diag(pe)])
+    _, diags = _schema.read_schema(d.root, "")
+    return _render_diags(diags)
+
+
+def _tomldoc_parse(src: bytes):
+    from strictspec import _tomldoc
+
+    return _tomldoc.parse(src)
+
+
+def run(req: dict) -> dict:
+    schema_path = req["schema"]
+    files, main = _build_fileset(schema_path)
+
+    # Meta-schema mode: the fixture's "document" is itself a schema file, read AS
+    # a document of the built-in meta-schema -- the reader's authoring diagnostics
+    # ARE the outcome.
+    s, _ = _schema.parse_from(files, main)
+    if s.name == "strictspec-meta-schema":
+        diagnostics = _meta_validate(req)
+        return {"valid": len(diagnostics) == 0, "diagnostics": diagnostics}
+
+    program = strictspec.compile_embedded(files, main)
+    src = _read_input(req)
+    evidence = req.get("evidence") or None
+    result = program.validate_with_evidence(src, req["input_syntax"], evidence)
+    diagnostics = [
+        {"code": d.code, "path": d.path, "message": d.message}
+        for d in result.diagnostics
+    ]
+    return {"valid": result.valid, "diagnostics": diagnostics}
+
+
+def main() -> int:
+    try:
+        req = json.load(sys.stdin)
+    except json.JSONDecodeError as exc:
+        json.dump({"error": f"bad request: {exc}"}, sys.stderr)
+        return 2
+    try:
+        resp = run(req)
+    except Exception as exc:  # noqa: BLE001 -- surface any failure to the harness
+        json.dump({"error": str(exc)}, sys.stderr)
+        return 2
+    json.dump(resp, sys.stdout)
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())