vinctor-core 0.2.0__tar.gz

vinctor_core-0.2.0/.dockerignore

@@ -0,0 +1,12 @@
+.git
+.venv
+.pytest_cache
+.ruff_cache
+__pycache__
+*.py[cod]
+*.egg-info
+dist
+build
+.vinctor
+.vinctor.env
+.vinctor-*.env

vinctor_core-0.2.0/.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,21 @@
+---
+name: Bug report
+about: Something doesn't behave as documented
+labels: bug
+---
+
+**What happened**
+
+**What you expected**
+
+**Repro steps**
+
+1.
+
+**Environment**
+
+- vinctor-core version / commit:
+- Python version:
+- OS:
+
+**Logs / output** (redact any secrets)

vinctor_core-0.2.0/.github/ISSUE_TEMPLATE/feature_request.md

@@ -0,0 +1,11 @@
+---
+name: Feature request
+about: Suggest an improvement to the authorization core or service layer
+labels: enhancement
+---
+
+**Problem / use case**
+
+**Proposed behavior**
+
+**Alternatives considered**

vinctor_core-0.2.0/.github/pull_request_template.md

@@ -0,0 +1,19 @@
+## Summary
+
+<!-- What does this change, and why? -->
+
+## Testing
+
+```
+make test
+make lint
+make demo
+```
+
+## Checklist
+
+- [ ] Tests added/updated and green (`make test` + `make lint` + the demo scripts)
+- [ ] Fail-closed preserved (no deny/error became a permit)
+- [ ] No secrets, raw keys, or grant existence leaked in deny reasons or audit
+- [ ] Schema changes additive + every schema-version assertion bumped (if applicable)
+- [ ] Docs / ADR updated if behavior or the contract changed

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

@@ -0,0 +1,65 @@
+name: CI
+
+on:
+  push:
+    branches: ["main"]
+  pull_request:
+
+jobs:
+  test:
+    name: Python 3.11
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5  # v4
+
+      - name: Set up Python
+        uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065  # v5
+        with:
+          python-version: "3.11"
+
+      - name: Install package
+        run: python -m pip install -e ".[dev]"
+
+      - name: Run tests
+        run: python -m pytest -q
+
+      - name: Run E2E demo
+        run: python demo/boundary_registry_core_e2e.py
+
+      - name: Run in-memory service demo
+        run: python demo/in_memory_v1_service_demo.py
+
+      - name: Run SQLite grant/audit demo
+        run: python demo/sqlite_grant_audit_demo.py
+
+      - name: Run SQLite boundary registry demo
+        run: python demo/sqlite_boundary_registry_demo.py
+
+      - name: Run SQLite V1 service demo
+        run: python demo/sqlite_v1_service_demo.py
+
+      - name: Run V1 HTTP contract demo
+        run: python demo/v1_http_contract_demo.py
+
+      - name: Run local V1 HTTP service demo
+        run: python demo/local_v1_http_service_demo.py
+
+      - name: Run boundary admin HTTP demo
+        run: python demo/boundary_admin_http_demo.py
+
+      - name: Run local service launch helper demo
+        run: python demo/local_service_launch_helper_demo.py
+
+      - name: Run local service bootstrap demo
+        run: python demo/local_service_bootstrap_demo.py
+
+      - name: Run Ruff
+        run: ruff check .
+
+      - name: Build package
+        run: python -m build
+
+      - name: Check whitespace
+        run: git diff --check

vinctor_core-0.2.0/.github/workflows/release.yml

@@ -0,0 +1,107 @@
+name: Release
+
+# Cut a release by pushing a version tag, e.g. `git tag v0.1.0 && git push --tags`.
+# Out of the box (using the automatic GITHUB_TOKEN) this:
+#   - builds the sdist + wheel and attaches them to the GitHub Release,
+#   - builds and pushes the Docker image to GHCR (ghcr.io/<owner>/vinctor-core).
+# Publishing to PyPI is OPT-IN: set the repository variable PUBLISH_PYPI=true and
+# configure PyPI Trusted Publishing for this repo (or add a PYPI_API_TOKEN secret
+# and pass it to the publish step). See docs/deployment/self-hosting.md.
+
+on:
+  push:
+    tags: ["v*"]
+  workflow_dispatch:
+
+permissions:
+  contents: write
+  packages: write
+
+jobs:
+  build:
+    name: Build distributions
+    runs-on: ubuntu-latest
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5  # v4
+
+      - name: Set up Python
+        uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065  # v5
+        with:
+          python-version: "3.11"
+
+      - name: Build sdist + wheel
+        run: |
+          python -m pip install --upgrade build
+          python -m build
+
+      - name: Upload dist artifacts
+        uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02  # v4
+        with:
+          name: dist
+          path: dist/
+
+      - name: Attach to GitHub Release
+        if: startsWith(github.ref, 'refs/tags/')
+        uses: softprops/action-gh-release@3bb12739c298aeb8a4eeaf626c5b8d85266b0e65  # v2
+        with:
+          files: dist/*
+
+  docker:
+    name: Build + push image (GHCR)
+    runs-on: ubuntu-latest
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5  # v4
+
+      - name: Log in to GHCR
+        uses: docker/login-action@c94ce9fb468520275223c153574b00df6fe4bcc9  # v3
+        with:
+          registry: ghcr.io
+          username: ${{ github.actor }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Image metadata
+        id: meta
+        uses: docker/metadata-action@c299e40c65443455700f0fdfc63efafe5b349051  # v5
+        with:
+          images: ghcr.io/${{ github.repository }}
+          tags: |
+            type=semver,pattern={{version}}
+            type=ref,event=tag
+            type=raw,value=latest,enable=${{ startsWith(github.ref, 'refs/tags/') }}
+
+      - name: Build and push
+        uses: docker/build-push-action@10e90e3645eae34f1e60eeb005ba3a3d33f178e8  # v6
+        with:
+          context: .
+          # Push only for tag releases; workflow_dispatch is a build-only smoke check.
+          push: ${{ startsWith(github.ref, 'refs/tags/') }}
+          tags: ${{ steps.meta.outputs.tags }}
+          labels: ${{ steps.meta.outputs.labels }}
+          # Supply-chain attestations attached to the pushed image.
+          provenance: true
+          sbom: true
+
+  pypi:
+    name: Publish to PyPI (opt-in)
+    needs: build
+    runs-on: ubuntu-latest
+    # Opt-in: set repository variable PUBLISH_PYPI=true to enable.
+    if: ${{ vars.PUBLISH_PYPI == 'true' && startsWith(github.ref, 'refs/tags/') }}
+    environment: pypi
+    permissions:
+      id-token: write  # PyPI Trusted Publishing (OIDC) — no stored token needed once configured
+    steps:
+      - name: Download dist artifacts
+        uses: actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093  # v4
+        with:
+          name: dist
+          path: dist/
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@cef221092ed1bacb1cc03d23a2d87d1d172e277b  # release/v1
+        # Uses Trusted Publishing when configured on PyPI. To use a token instead,
+        # add a PYPI_API_TOKEN secret and uncomment:
+        # with:
+        #   password: ${{ secrets.PYPI_API_TOKEN }}

vinctor_core-0.2.0/.gitignore

@@ -0,0 +1,13 @@
+.venv/
+.pytest_cache/
+.ruff_cache/
+__pycache__/
+*.py[cod]
+*.egg-info/
+dist/
+build/
+.DS_Store
+.vinctor/
+.vinctor-local.sqlite
+.vinctor.env
+.vinctor-*.env

vinctor_core-0.2.0/AGENTS.md

@@ -0,0 +1,97 @@
+# AGENTS.md
+
+Guidance for AI coding agents working in this repository.
+
+## Project Shape
+
+`vinctor-core` starts with the deterministic authorization core for mediated
+AI-agent actions. It evaluates explicit authorization inputs and returns
+deterministic decision/audit data.
+
+Service-layer packages may live here as the implementation matures, but must
+remain layered above the core. Keep core behavior small, deterministic, and
+runtime-agnostic.
+
+## Hard Boundaries
+
+Do not add runtime-specific code to `vinctor_core`.
+
+Layering rule:
+
+- `vinctor_core` must not import `vinctor_service`.
+- `vinctor_service` may import `vinctor_core`.
+- `vinctor_core` remains DB/HTTP/runtime-agnostic.
+- `vinctor_service` owns HTTP APIs, auth headers, persistence, and
+  workspace/agent/grant/boundary/audit storage.
+
+Do not implement:
+
+- Claude Code, Codex, Hermes, LangGraph, or MCP hooks
+- HTTP service endpoints unless a task explicitly asks for a service package
+- durable database persistence unless a task explicitly asks for it
+- prompt/content safety logic
+- raw tool interception
+- sandboxing or OS/process isolation
+- provider integrations
+- approval workflows
+- hosted service behavior
+- UI/dashboard behavior
+
+Runtime adapters translate tool calls into action/resource pairs. Service
+layers handle authentication and persistence. This core evaluates explicit
+authorization inputs.
+
+## Sibling Runtime Repositories
+
+Do not directly edit or push sibling hook/plugin repositories from this
+repository's workstream. If Vinctor core work reveals a needed hook change,
+document the request here or open an issue/PR for the sibling repo owner to
+review.
+
+## Development Workflow
+
+Use a small, test-first loop:
+
+1. Define the behavior with tests.
+2. Implement the minimum code needed to pass.
+3. Run the relevant tests.
+4. Simplify the diff.
+5. Update docs only when public behavior or agent workflow changes.
+
+Prefer pure functions and small typed dataclasses. Avoid heavy class hierarchies
+or speculative extension points.
+
+## Validation
+
+Use:
+
+```bash
+/opt/homebrew/bin/python3.11 -m venv .venv
+.venv/bin/python -m pip install -e ".[dev]"
+.venv/bin/python -m pytest -q
+.venv/bin/python demo/boundary_registry_core_e2e.py
+.venv/bin/ruff check .
+.venv/bin/python -m build
+git diff --check
+```
+
+When using the local venv created for this repo:
+
+```bash
+.venv/bin/python -m pytest -q
+.venv/bin/python demo/boundary_registry_core_e2e.py
+.venv/bin/ruff check .
+.venv/bin/python -m build
+git diff --check
+```
+
+## Documentation
+
+Keep docs small and current.
+
+- `README.md` explains the public package boundary.
+- `docs/next-actions.md` tracks current work and the next useful tasks.
+- `docs/decisions/` records durable decisions only when needed.
+
+Do not create architecture-only documents as a substitute for implemented,
+tested behavior.

vinctor_core-0.2.0/CODE_OF_CONDUCT.md

@@ -0,0 +1,23 @@
+# Code of Conduct
+
+We are committed to a friendly, safe, and welcoming environment for everyone.
+
+We pledge to make participation a harassment-free experience regardless of age,
+body size, disability, ethnicity, gender identity and expression, level of
+experience, nationality, personal appearance, race, religion, or sexual identity
+and orientation.
+
+Examples of unacceptable behavior include harassment, insulting or derogatory
+comments, public or private harassment, and publishing others' private information
+without permission.
+
+This Code of Conduct adapts the
+[Contributor Covenant](https://www.contributor-covenant.org/version/2/1/code_of_conduct/),
+version 2.1.
+
+## Enforcement
+
+Report unacceptable behavior privately to the maintainers via the repository's
+*Security* tab -> *Advisories* -> [Report a vulnerability](../../security/advisories/new),
+which routes privately to the maintainers. All complaints will be reviewed and
+investigated promptly and fairly.

vinctor_core-0.2.0/CONTRIBUTING.md

@@ -0,0 +1,52 @@
+# Contributing
+
+`vinctor-core` is the deterministic authorization core for mediated AI-agent
+actions, plus a thin `vinctor_service` application layer above it. Contributions
+are welcome — the goal is to keep the core small, explicit, and reviewable.
+
+## Dev setup
+
+Python >= 3.11. Editable install with dev tools:
+
+```bash
+python3.11 -m venv .venv
+.venv/bin/python -m pip install -e ".[dev]"
+```
+
+## Quality gates
+
+Before committing (CI runs the same on every PR):
+
+```bash
+make test     # python -m pytest -q
+make lint     # python -m ruff check .
+make demo     # the demo scripts, which CI also executes
+```
+
+PRs must be green on the full suite, `ruff check`, and the demo scripts.
+
+## Conventions
+
+- **stdlib + PyYAML only.** No new runtime dependencies without discussion — the
+  dependency surface is deliberately tiny. Lint is `ruff check` only (not `ruff format`).
+- **Test-first.** New behavior or a bug fix lands with a test that fails before the
+  change and passes after.
+- **Fail closed.** No change may turn a deny — or an error — into a permit. This is
+  the core invariant, and tests pin it.
+- **No disclosure in deny reasons or audit.** Deny reasons and audit events must not
+  leak secrets, raw keys, or even grant existence (an unknown grant and a foreign
+  grant return the same generic 403). Resources are hierarchical path-prefixes, so
+  `.` / `..` traversal segments are rejected. Don't interpolate caller input into
+  reasons — the no-disclosure tests enforce this.
+- **Schema changes are additive and versioned** (`schema_migrations`); bump every
+  schema-version assertion across the tests when you add a version.
+- **Surgical diffs.** Match the surrounding style; don't refactor unrelated code.
+
+## Branch / PR model
+
+`main` is human-merged only — work on a feature branch and open a PR. Architecture
+and design decisions live in `docs/decisions/` (ADRs) and elsewhere under `docs/`.
+
+## Security
+
+Found a vulnerability? See [SECURITY.md](SECURITY.md) — please don't use public issues.

vinctor_core-0.2.0/Dockerfile

@@ -0,0 +1,31 @@
+# TODO: pin by digest (FROM python:3.11-slim@sha256:<digest>  # 3.11-slim) once
+# a digest can be resolved in CI (e.g. `docker buildx imagetools inspect`).
+FROM python:3.11-slim
+
+WORKDIR /app
+
+COPY pyproject.toml README.md ./
+COPY src ./src
+
+RUN python -m pip install --no-cache-dir .
+
+# Run as an unprivileged system user; own the data directory it writes to.
+RUN useradd --system --uid 10001 vinctor \
+    && mkdir -p /data \
+    && chown vinctor:vinctor /data
+
+ENV VINCTOR_HOST=0.0.0.0
+ENV VINCTOR_PORT=8765
+ENV VINCTOR_DB=/data/vinctor.sqlite
+ENV VINCTOR_SERVICE_MODE=self_hosted
+ENV VINCTOR_LOG_LEVEL=info
+
+EXPOSE 8765
+
+# Probe the service health endpoint with the stdlib (no curl in python-slim).
+HEALTHCHECK --interval=30s --timeout=3s --start-period=5s CMD \
+    python -c "import urllib.request,os;urllib.request.urlopen('http://127.0.0.1:'+os.environ.get('VINCTOR_PORT','8765')+'/healthz').read()"
+
+USER vinctor
+
+CMD ["vinctor", "service", "serve"]

vinctor_core-0.2.0/LICENSE

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

vinctor_core-0.2.0/Makefile

@@ -0,0 +1,26 @@
+PYTHON ?= .venv/bin/python
+VINCTOR ?= .venv/bin/vinctor
+
+.PHONY: install-dev test lint demo demo-self-host demo-mock build
+
+install-dev:
+	$(PYTHON) -m pip install -e ".[dev]"
+
+test:
+	$(PYTHON) -m pytest -q
+
+lint:
+	$(VINCTOR) --help >/dev/null
+	$(PYTHON) -m ruff check .
+
+demo:
+	$(VINCTOR) demo service
+
+demo-self-host:
+	$(PYTHON) demo/self_hostable_service_demo.py
+
+demo-mock:
+	$(PYTHON) demo/mock_vinctor_service_demo.py
+
+build:
+	$(PYTHON) -m build

vinctor_core-0.2.0/OPEN-issues.md

@@ -0,0 +1,10 @@
+# Open Issues — vinctor-core
+Living tracker so already-fixed items are not re-worked. Code is the source of truth for "resolved" — re-verify before re-routing.
+
+## Open
+- (none currently tracked — add as discovered)
+
+## Recently resolved — do NOT re-route
+- F1 (2026-06-18): design-partner E2E setup helper now writes the hook config and exports VINCTOR_CLAUDE_CODE_HOOK_CONFIG (demo/claude_code_design_partner_e2e_setup.py).
+- F6 (2026-06-18): vinctor_mcp_server/server.py has a __main__ guard — `python -m vinctor_mcp_server.server` serves over stdio.
+- local-start UX (this PR): EADDRINUSE on a busy port exits with a friendly CliError instead of a raw traceback; restart hint emits `vinctor local start …`; corrected the "fixed test clock" note (frozen clock is pytest-only).