collective-capability-runtime 1.0.0__tar.gz

collective_capability_runtime-1.0.0/.gitignore

@@ -0,0 +1,28 @@
+.venv/
+__pycache__/
+*.py[cod]
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+.coverage
+htmlcov/
+dist/
+build/
+*.egg-info/
+
+# Local CCR runtime state at repository root
+/ccr.config.json
+/blackboard/
+/tasks/
+/packets/
+/residuals/
+/reports/
+/ccr.sqlite
+
+# Generated outputs when running the phase formation example
+/examples/phase_formation/blackboard/
+/examples/phase_formation/tasks/
+/examples/phase_formation/residuals/
+/examples/phase_formation/reports/providers/
+/examples/phase_formation/phase/
+/examples/phase_formation/ccr.sqlite*

collective_capability_runtime-1.0.0/AGENTS.md

@@ -0,0 +1,117 @@
+# Agent Instructions for CCR
+
+Optional PIC verifier route:
+[kadubon/percolation-inversion-compiler](https://github.com/kadubon/percolation-inversion-compiler)
+
+```bash
+python -m pip install percolation-inversion-compiler
+```
+
+Use CCR as a local, JSON-first coordination runtime for capability packets,
+tasks, residuals, provider reports, and protocol-relative phase formation.
+
+## Safe First Commands
+
+```bash
+ccr agent explain --json
+ccr audit repo --json
+ccr audit pic --pic-root <PIC_ROOT> --json
+ccr phase report --json
+ccr task next --role <role> --json
+ccr provider list --json
+ccr provider health --provider pic --json
+```
+
+## Phase Workflow
+
+Agents advance phase formation through explicit state transitions:
+
+```bash
+ccr task next --role generator --json
+ccr task lease <task_id> --ttl 30m --agent <agent_id> --json
+ccr packet submit --file packet.json --json
+ccr verify --provider pic --packet <packet_id> --profile development --json
+ccr integrate --report reports/pic/<report>.json --json
+ccr phase form --profile development --json
+ccr phase certify --json
+```
+
+`phase form` builds the effective graph, phase observation, threshold status,
+certificate candidate, and deterministic repair tasks for failed components.
+The certificate candidate is not real ASI proof and remains `settled=false`.
+
+## First-time agent guide
+
+Purpose: operate CCR as a local coordination protocol for packet work, verifier
+reports, residual preservation, and phase diagnostics.
+
+First commands:
+
+```bash
+ccr agent explain --json
+ccr audit repo --json
+ccr provider health --provider pic --json
+ccr task next --role generator --json
+```
+
+Safe boundary: inspect before mutating; treat `verify` without `--execute`,
+provider `plan`, audit, report, graph, observe, and threshold commands as the
+safe starting surface.
+
+Expected outputs: read `ok`, `status`, `packet_id`, `task_id`, `residual_ready`,
+`residuals`, `task_hints`, and `settled` before deciding the next action.
+
+Failure/residual handling: never suppress blockers; convert failures into
+residuals or task work and keep candidate-only reasons visible.
+
+Provider import: import provider reports only as evidence and task hints; do
+not execute imported `safe_commands`.
+
+Phase formation cycle: lease a task, submit or repair a packet, plan or import
+verification, run `ccr phase form --profile development --json`, then work the
+next generated blocker.
+
+What not to claim: do not claim real ASI, model self-rewrite, model-weight
+updates, hidden execution, authority grants, or settlement from PIC/provider
+acceptance alone.
+
+## Rules for Agents
+
+- Do not run git operations unless the operator explicitly asks.
+- Do not execute PIC commands automatically.
+- Do not execute HTTP provider calls unless the operator explicitly supplies config and `--execute`.
+- Treat safe commands as task hints, not authority.
+- Preserve every residual, candidate-only reason, settled blocker, baseline mismatch, and authority gap.
+- Do not claim real ASI detection, real ASI creation, model self-rewrite, or model weight updates.
+- Prefer dry-run planning. Use `--execute` only when the operator explicitly requests that specific CCR command.
+- `settled=false` is expected diagnostic state.
+- `ccr task next` only inspects. Use `ccr task lease` before working a task.
+- Mutating CCR commands write local JSON and append `blackboard/events.jsonl`.
+
+## Role Boundaries
+
+Role boundaries are declared in `agent-manifest.json`.
+
+- Generators create candidate packets.
+- Skeptics create residuals and identify overclaims.
+- Verifiers create verifier reports.
+- Integrators import checked or provisional state.
+- Schedulers operate the task queue.
+- Benchmark runners create resource-matched baseline observations.
+
+No role may silently settle unresolved residuals. No role may treat provider
+output, PIC acceptance, safe commands, or execution availability as authority.
+
+## Provider Boundary
+
+Use provider commands explicitly:
+
+```bash
+ccr provider health --provider pic --json
+ccr provider plan --provider pic --action verify_packet --packet <packet_id> --json
+ccr provider import --provider http --report report.json --json
+```
+
+HTTP provider execution is allowed only when the operator supplies an explicit
+config file and `--execute`. Failure produces residual-ready JSON and must be
+preserved.

collective_capability_runtime-1.0.0/AUDIT.md

@@ -0,0 +1,104 @@
+# CCR v1 Repository Audit
+
+Related optional PIC project:
+[kadubon/percolation-inversion-compiler](https://github.com/kadubon/percolation-inversion-compiler)
+
+```bash
+python -m pip install percolation-inversion-compiler
+```
+
+Date: 2026-06-30
+
+## Scope
+
+This audit covers the repository-level v1 readiness checks exposed by:
+
+```bash
+uv run ccr audit repo --json
+uv run ccr audit pic --pic-root <PIC_ROOT> --json
+uv run ccr provider health --provider pic --json
+```
+
+`<PIC_ROOT>` is a placeholder for a local PIC source checkout, such as
+`../percolation-inversion-compiler`. Public files must not contain
+user-specific local paths.
+
+The audit checks README positioning, docs/security/agent guidance, required JSON
+schemas, CLI surface, CI presence, SPDX headers, provider safety language, and
+non-claim preservation. It also checks PyPI Trusted Publishing readiness for
+`.github/workflows/workflow.yml` and prevents generated phase runtime artifacts
+from being shipped as source examples.
+
+PIC compatibility audit checks the optional PIC source root, installed package
+and CLI availability, expected v0.5.0 commands, report fields, provider mapping,
+safe-command handling, and the rule that PIC output never settles CCR by itself.
+
+Public release audit checks source files and built wheel/sdist archives for
+local path leakage, generated runtime artifacts, caches, build state, private-key
+blocks, and assignment-like credentials:
+
+```bash
+uv build
+uv run ccr audit release --dist dist --json
+uvx twine check dist/*
+```
+
+## First-time agent guide
+
+Purpose: run repository and PIC audits before trusting a local CCR checkout for
+agent work or release publication.
+
+First commands:
+
+```bash
+ccr audit repo --json
+ccr audit pic --pic-root <PIC_ROOT> --json
+ccr provider health --provider pic --json
+```
+
+Safe boundary: audits inspect files, docs, schemas, workflows, provider routes,
+and compatibility markers; they do not execute provider safe commands.
+
+Expected outputs: audit reports contain `ok`, finding counts, blocking flags,
+finding ids, and `residual_ready` objects for every issue.
+
+Failure/residual handling: a failed audit is actionable protocol state; preserve
+the finding and repair it before release or settlement promotion.
+
+Provider import: audit validates the import boundary but does not import or
+execute provider reports itself.
+
+Phase formation cycle: repository audit checks that phase formation examples,
+schemas, docs, CI, and non-claims remain aligned before agents rely on them.
+
+What not to claim: a passing audit means the release gates are satisfied; it is
+not proof of real ASI, external authority, or provider execution.
+
+## Current Findings
+
+Blocking findings: none after the v1 implementation pass.
+
+Non-blocking findings: none expected after SPDX header cleanup.
+
+Residual policy: any future audit finding is emitted with a `residual_ready`
+object so agents can preserve the issue without corrupting runtime state.
+
+## Acceptance Commands
+
+```bash
+uv sync --all-extras
+uv run ruff check .
+uv run pytest
+uv run ccr audit repo --json
+uv run ccr audit pic --pic-root <PIC_ROOT> --json
+uv run ccr --root examples/phase_formation phase form --profile development --json
+uv build
+uv run ccr audit release --dist dist --json
+uvx twine check dist/*
+```
+
+## Non-Claims Preserved
+
+CCR does not prove real ASI, create real ASI, self-modify models, update model
+weights, grant execution authority, bypass safety, or convert PIC/provider
+output into settled capability by itself.

collective_capability_runtime-1.0.0/CHANGELOG.md

@@ -0,0 +1,22 @@
+# Changelog
+
+## 1.0.0 - 2026-06-30
+
+- Added SQLite indexing while preserving JSON artifacts as source records.
+- Added v1 phase formation engine: effective graph, observation, threshold,
+  baseline comparison, formation cycle, and certificate candidate generation.
+- Added provider API with PIC and HTTP providers.
+- Added repository audit command and v1 phase/provider/audit schemas.
+- Added phase formation examples and v1 documentation.
+- Added PIC route documentation for
+  [kadubon/percolation-inversion-compiler](https://github.com/kadubon/percolation-inversion-compiler)
+  and `python -m pip install percolation-inversion-compiler`.
+
+## 0.1.0 - 2026-06-30
+
+- Added initial CCR Python package and `ccr` CLI.
+- Added local runtime initialization, task queue, task leasing, packet submission,
+  packet promotion, residual ledger, blackboard events, phase reports, and PIC
+  dry-run/execute adapter.
+- Added normative packet and task schema usage plus additional runtime schemas.
+- Added examples, tests, Apache-2.0 licensing, and GitHub Actions CI.

collective_capability_runtime-1.0.0/CODE_OF_CONDUCT.md

@@ -0,0 +1,14 @@
+# Code of Conduct
+
+CCR uses a neutral technical collaboration standard.
+
+Participants should:
+
+- focus on evidence, reproducibility, and concrete behavior
+- separate claims from verification status
+- preserve uncertainty and residuals rather than hiding them
+- avoid harassment, discrimination, and personal attacks
+- report security-sensitive issues through appropriate private channels when available
+
+Maintainers may remove contributions or comments that undermine a safe and
+productive technical environment.

collective_capability_runtime-1.0.0/CONTRIBUTING.md

@@ -0,0 +1,53 @@
+# Contributing
+
+Related optional PIC project:
+[kadubon/percolation-inversion-compiler](https://github.com/kadubon/percolation-inversion-compiler)
+
+```bash
+python -m pip install percolation-inversion-compiler
+```
+
+## Setup
+
+```bash
+python -m pip install collective-capability-runtime
+uv sync
+uv run ccr agent explain --json
+```
+
+## Tests
+
+```bash
+uv run ruff check .
+uv run pytest
+uv run ccr audit repo --json
+uv build
+uvx twine check dist/*
+```
+
+## Coding Style
+
+- Use the `src/` layout.
+- Keep JSON outputs stable and machine-readable.
+- Keep side effects local and explicit.
+- Preserve residuals instead of deleting uncertainty.
+- Add SPDX headers to Python source files.
+- Prefer standard-library implementations unless a dependency removes real risk.
+
+## Schema Changes
+
+Schema changes must update:
+
+- `schemas/*.schema.json`
+- examples
+- tests
+- `SPEC.md`
+- `CHANGELOG.md`
+
+Do not perform git operations unless the operator explicitly asks.
+
+## Release Preparation
+
+CCR publishes as `collective-capability-runtime` through GitHub Trusted
+Publishing. The release workflow is `.github/workflows/workflow.yml` and must
+not require PyPI token, username, or password secrets.

collective_capability_runtime-1.0.0/FORMAL_MODEL.md

@@ -0,0 +1,229 @@
+# CCR Formal Model v1
+
+Related PIC runtime: [kadubon/percolation-inversion-compiler](https://github.com/kadubon/percolation-inversion-compiler).
+
+```bash
+python -m pip install percolation-inversion-compiler
+```
+
+PIC is an optional verifier relation. It is not a CCR settlement oracle.
+
+CCR is a finite transition system over JSON artifacts plus a SQLite index.
+
+## First-time agent guide
+
+Purpose: use the formal model to understand why CCR separates admissible
+packet work, residual debt, execution availability, provider evidence, and
+phase-candidate status.
+
+First commands:
+
+```bash
+ccr agent explain --json
+ccr phase graph --json
+ccr phase observe --json
+ccr phase form --profile development --json
+```
+
+Safe boundary: every formal relation is protocol-relative and finite; execution
+availability is a witness relation, not an execution trace.
+
+Expected outputs: graph, observation, threshold, comparison, and certificate
+candidate artifacts expose finite metrics, blockers, reasons, and `settled=false`.
+
+Failure/residual handling: failed predicates become residual debt, failed
+components, abstention reasons, or repair tasks rather than hidden state.
+
+Provider import: provider reports enter the model as external evidence
+relations and residual sources, not as direct settlement functions.
+
+Phase formation cycle: repeated packet verification, residual reduction,
+effective-edge construction, and resource-matched comparison can improve a
+protocol-relative candidate phase.
+
+What not to claim: the model does not assert metaphysical ASI, oracle truth,
+physical outcome truth, autonomous authority, self-rewrite, or model-weight
+change.
+
+## Packet
+
+A packet is:
+
+```text
+P = (id, status, claims, artifacts, scope, provenance, verifiers,
+     verifier_reports, residuals, risk, reuse, lineage, execution_availability,
+     pic_interop)
+```
+
+`status(P)` is an element of the packet lattice in `SPEC.md`.
+
+Positive phase contribution is:
+
+```text
+Positive(P) =
+  status(P) in {checked, settled}
+  AND no_open_blocking_residual(P)
+  AND authority_valid(P)
+  AND liquidity_lower_bound(P) >= 0
+```
+
+Candidate-only packet volume is observed but excluded from `Positive`.
+
+## Task
+
+A task is:
+
+```text
+T = (id, status, role, priority, objective, inputs, expected_outputs,
+     constraints, lease, verifier_plan, residual_policy, pic_interop)
+```
+
+The scheduler returns the open task with maximal `(priority, -created_at, id)`
+for the requested role. Leasing is a separate transition.
+
+## Residual Ledger
+
+A residual is:
+
+```text
+R = (id, status, severity, kind, description, blocking, object_ref, source)
+```
+
+Residual preservation invariant:
+
+```text
+failed_validation OR failed_promotion OR candidate_only_reason
+OR settled_blocker OR authority_gap OR provider_failure OR baseline_mismatch
+=> residual OR residual_ready_object
+```
+
+## Effective Graph
+
+The effective graph is:
+
+```text
+G_eff = (V, E, eligibility, contribution)
+```
+
+where `V` contains local packets and `E` contains dependency or semantic edges.
+An edge contributes positively only when all incident packet nodes are positive
+and edge evidence is checked or settled. Raw/candidate/rejected/quarantined mass
+does not increase positive graph metrics.
+
+## Execution Availability
+
+Execution availability is a witness relation:
+
+```text
+ExAv(P, gate_set, side_effect_policy, rollback)
+```
+
+It is not an execution trace:
+
+```text
+ExAv(P, ...) does not imply Executed(P)
+```
+
+CCR phase observations set `executed_path_count = 0` unless an explicit future
+schema introduces a separate execution evidence type. v1 does not introduce that
+type.
+
+## Observation
+
+A phase observation is:
+
+```text
+O = metrics(G_eff, residual_ledger, queue_state)
+```
+
+with components:
+
+```text
+accepted_packet_count
+effective_edge_count
+execution_available_path_density
+autocatalytic_closure_score
+verification_throughput
+residual_debt
+false_liquidity_load
+salience_obstruction_load
+```
+
+## Threshold Predicate
+
+An ASI-proxy threshold is a protocol-relative predicate:
+
+```text
+Theta(O) -> {accepted, abstain, rejected}
+```
+
+`Theta(O)=accepted` means the finite CCR protocol threshold is satisfied. It
+does not assert real ASI, oracle truth, physical outcome truth, or model-weight
+change.
+
+## Baseline Predicate
+
+Baseline comparison is:
+
+```text
+B = (resource_envelope, comparison_class, metrics, validity_domain)
+Compare(B, O) -> (resource_matched, deltas, residual_ready)
+```
+
+If `resource_envelope(B) != resource_envelope(O)`, comparison emits a blocking
+residual-ready object. The mismatch is preserved rather than discarded.
+
+## Certificate Candidate
+
+A collective phase certificate candidate is:
+
+```text
+C = (G_eff, O, Theta(O), residual_obligations, baseline_obligations)
+```
+
+`accepted(C)` requires threshold acceptance and no blocking residual obligations.
+`settled(C)` is always false in v1. Promotion to a settled phase claim would
+require a future verifier-controlled settlement gate beyond CCR's candidate.
+
+## Provider Relation
+
+A provider relation is:
+
+```text
+Provider(plan | execute | normalize)
+```
+
+Planning is non-executing. Execution requires explicit operator authority. A
+provider report is evidence input, not settlement authority.
+
+## Promotion Predicate
+
+Candidate to checked:
+
+```text
+schema_valid(P)
+AND at_least_one_required_verifier_accepts(P)
+AND residuals_preserved(P)
+AND no_authority_bypass(P)
+```
+
+Checked to settled:
+
+```text
+checked(P)
+AND no_blocking_residuals(P)
+AND settlement_target_satisfied(P)
+AND lineage_closed(P)
+AND scope_declared(P)
+AND risk_in_envelope(P)
+AND integration_policy_passed(P)
+AND phase_baseline_residual_gates_pass_if_phase_claim(P)
+```
+
+For v1, residual waivers are not implemented. Settlement fails closed.
+
+## Non-Claims
+
+CCR does not detect real ASI, create real ASI, update model weights, self-modify
+models, grant execution authority, bypass safety, or convert provider output
+into settled capability by itself.

collective_capability_runtime-1.0.0/GOVERNANCE.md

@@ -0,0 +1,59 @@
+# Governance
+
+Related optional PIC project:
+[kadubon/percolation-inversion-compiler](https://github.com/kadubon/percolation-inversion-compiler)
+
+```bash
+python -m pip install percolation-inversion-compiler
+```
+
+PIC integration is optional and cannot bypass CCR release, schema, residual, or
+settlement policy.
+
+## Release Policy
+
+CCR follows semantic versioning from v1.0. Stable v1 interfaces are CLI commands
+and JSON schemas. The Python API is semi-stable and may evolve with migration
+notes.
+
+PyPI releases use the project name `collective-capability-runtime` and GitHub
+Trusted Publishing from `kadubon/collective-capability-runtime`. Publication is
+allowed only from the release workflow `.github/workflows/workflow.yml`.
+
+## Compatibility Policy
+
+Local schemas are authoritative. Packaged schemas are fallbacks for installed
+usage. A command must not silently accept an incompatible unknown schema version.
+
+## Schema Versioning
+
+Schema versions use the form:
+
+```text
+ccr.<object>.v<major>[.<minor>]
+```
+
+Breaking schema changes require:
+
+- changelog entry
+- updated examples
+- updated tests
+- documented migration route
+
+New phase, baseline, provider, or audit schemas must preserve non-claim fields
+where applicable: `protocol_relative_only=true`, `proves_real_asi=false`, and
+`settled=false`.
+
+## Side-Effect Changes
+
+Any change that adds external side effects, network behavior, command execution,
+or broader filesystem mutation requires maintainer review and an explicit
+documentation update.
+
+Provider additions must default to dry-run planning, expose health and
+capabilities, require explicit execution authority, and preserve failure
+residuals.
+
+Publish workflow changes must keep `id-token: write`, avoid PyPI token secrets,
+and run build, lint, tests, audit, and distribution metadata checks before
+publishing.