{
  "markdown": "# SeedCore\n\n[![Unit Tests](https://github.com/NeilLi/seedcore/actions/workflows/unit-tests.yml/badge.svg)](https://github.com/NeilLi/seedcore/actions/workflows/unit-tests.yml)\n[![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](LICENSE)\n\n## Governed Execution and Trust Runtime for Autonomous Systems\n\nAgent frameworks decide **what to do**. Prompt guardrails control **what is said**. SeedCore controls **what is allowed to execute**.\n\nSeedCore is a zero-trust execution and proof runtime for high-consequence autonomous workflows. It sits between advisory AI intent and real-world execution, then checks identity, delegation, policy scope, asset state, policy or graph mutation provenance, hardware or custody boundaries, and evidence requirements before execution authority can exist.\n\nUnlike a model guardrail, tool-calling wrapper, or heuristic security detector, SeedCore is a deterministic execution gate:\n\n- rejects ambient or implicit authority\n- mints short-lived, scoped `ExecutionToken`s only after policy admits an `ActionIntent`\n- preserves signed receipts, transition evidence, and replayable bundles for post-hoc verification\n\nThe core principle is simple:\n\n```text\nAI intent should not automatically become execution authority.\nThe model can propose. The Agent is accountable. The PDP decides.\nThe actuator executes. The evidence closes the loop.\n```\n\n## What SeedCore Protects Against\n\nSeedCore is designed for systems where autonomous agents must not be able to turn diagnosis, planning, local state, or self-healing output into authority by themselves. In the current runtime, that means protecting against:\n\n- self-approval of policy or authorization graph changes\n- mutation of the rules that govern the agent's next execution token\n- bypass through local cache, filesystem, or stale active graph state\n- high-impact execution without a scoped `ExecutionToken`\n- policy or infrastructure drift that is not tied to replayable evidence\n- custody, commerce, deployment, or quarantine actions without forensic closure\n\n## Current Status\n\nSeedCore already has an implemented and contract-tested baseline for the trust-runtime slice: Agent Action Gateway v1, `ExecutionToken` lifecycle, stateless PDP evaluation, active authorization graph checks, evidence bundles, replay verification, Rust proof-kernel paths, and a coordinator-embedded `RESULT_VERIFIER` for Restricted Custody Transfer (RCT) enforcement.\n\nThe current product focus is narrower and deliberately commercial: package that baseline into an **Agent-Governed Restricted Custody Transfer** workflow, with a collectible rare-shoe custody handoff as the first legible vertical scene.\n\nImportant boundaries:\n\n- The rare-shoe scene is an active verticalization of the existing RCT runtime, not a sneaker marketplace.\n- SeedCore proves governed custody movement and evidence integrity; it does not assert legal ownership transfer in v0.\n- Host-mode local runtime verification is green end-to-end for the RCT wedge: the Agent Action Gateway can generate a replayable runtime audit row, the verification API can read queue/detail/replay/runbook views from it, and the productized verification surface protocol passes locally.\n- Remote Kind/Kubernetes hot-path validation is green for API, Ray, HAL, ingress, Redis resilience, and hot-path observability. Full live verification-surface signoff in that topology still depends on capturing runtime audit rows there.\n- The rare-shoe RCT dynamic NFC simulation lane is implemented and workspace-verified: deterministic fixture evidence covers happy path, replay / clone, stale scan, wrong asset, tamper, and incomplete payload cases without making mock NFC an authority source.\n- The first immutable policy-anchor slice is implemented: AI-origin authz graph inputs fail closed unless accompanied by a co-signed promotion receipt bound to the exact graph version and snapshot hash. The current slice validates receipt structure and graph binding; full KMS/key-registry signature verification remains a follow-on hardening step.\n\nRead the current execution docs:\n\n- [Development docs index](docs/development/README.md)\n- [Current next steps](docs/development/current_next_steps.md)\n- [2026 execution plan](docs/development/seedcore_2026_execution_plan.md)\n- [Kube topology validation Q2 signoff](docs/development/kube_topology_validation_q2_signoff.md)\n- [Rare-shoe RCT demo spec](docs/development/rare_shoes_collecting_transfer_demo_spec.md)\n\n## Trust Runtime, Not Traditional Cybersecurity\n\nSeedCore uses zero-trust language, but it is not primarily a perimeter-defense product. Traditional cybersecurity protects environments by detecting threats, hardening boundaries, or blocking suspicious behavior. SeedCore governs execution **inside** an environment: it decides whether a proposed action is admissible, issues bounded authority when policy allows it, and produces proof explaining what happened afterward.\n\n```text\nCybersecurity protects the environment.\nSeedCore governs execution within it.\n```\n\n| Feature | Traditional cybersecurity | SeedCore Trust Runtime |\n| --- | --- | --- |\n| Primary goal | Detect threats, reduce attack success, harden perimeters | Govern admissible action and produce replayable proof |\n| Primary question | \"Is this malicious or suspicious?\" | \"Is this action admissible under policy and authority?\" |\n| Decision core | Heuristic, anomaly-based, or signature-driven | Synchronous, stateless Policy Decision Point (PDP) |\n| Runtime output | Alerts, blocks, detections, logs | Signed tokens, transition receipts, forensic bundles |\n| Success metric | Breaches prevented or detected | Cryptographic verifiability and replayability of state transitions |\n\nFor the canonical category framing, see [Trust Runtime Category Distinction](docs/development/trust_runtime_category_distinction.md).\n\n## Commercial Wedge: Restricted Custody Transfer\n\nThe must-win product wedge is **Agent-Governed Restricted Custody Transfer (RCT)**: a governed path where digital transaction identity is bound to physical custody, scope, and evidence before SeedCore issues execution authority.\n\nThe current commerce-shaped integration maps Shopify-Sandbox-style fields into the gateway and proof surface:\n\n```text\nproduct_ref + order_ref + quote_ref + declared_value_usd + economic_hash\n```\n\nThe first commercial scene is **Collectible Rare-Shoe Custody Handoff**. Rare shoes make the trust failures obvious: counterfeit risk, stale authentication, swapped assets, condition drift, replay attacks, and opaque custody. The same proof pattern is relevant to luxury logistics, regulated parts, lab samples, robotics handoff, and other high-value physical workflows.\n\n```text\nSeller / consignor\n  -> Authenticator signs provenance, condition, and NFC/scan evidence\n  -> Buyer or buyer agent expresses intent\n  -> SeedCore PDP evaluates authority, policy, scope, and evidence\n  -> Courier or edge operator receives bounded execution authority\n  -> RESULT_VERIFIER replays the chain and closes or quarantines the case\n```\n\nCommercial actors stay explicit:\n\n- **Seller / consignor** submits the physical asset for registration and sale.\n- **Authenticator** provides authentication, condition grade, and evidence refs.\n- **Marketplace / listing partner** provides `product_ref`, `quote_ref`, `order_ref`, and value context.\n- **Buyer and buyer agent** express commercial intent, but cannot authorize custody alone.\n- **Courier / edge operator** executes only inside scoped, time-bounded authority.\n- **Verifier** replays the evidence chain and surfaces verified, rejected, review, or quarantine outcomes.\n\n## Implemented Runtime Capabilities\n\nSeedCore's current baseline includes the technical primitives needed for governed execution:\n\n- **Stateless PDP and compiled authz graph**: deterministic evaluation of `ActionIntent` against policy, OPA/WASM support, and ReBAC graph paths.\n- **AI-origin graph mutation gate**: active and explicitly supplied compiled authz graph inputs are checked for AI-origin provenance; un-co-signed or incorrectly bound graph promotions fall back to the pinned path and emit a `trust_alert` for replay and audit surfaces.\n- **Short-lived `ExecutionToken`s**: bounded capability artifacts with TTL, frozen constraints, execution preconditions, Redis CRL revocation, and local development fallbacks.\n- **Coordinator-embedded `RESULT_VERIFIER`**: a background runtime that polls `digital_twin_event_journal`, persists verifier jobs and outcomes, reuses the replay path, calls the Rust proof kernel, and fail-closes RCT state on terminal mismatch.\n- **Replayable evidence bundles**: policy receipts, execution tokens, transition receipts, telemetry refs, and source-preserving replay bundles for independent verification.\n- **Hardware-anchored telemetry path**: signed transition receipts and telemetry envelopes, with TPM/KMS-backed signing posture for attested deployments and software-backed signing for local development.\n- **Virtual NFC simulation verifier**: deterministic dynamic NFC challenge-response fixtures for the rare-shoe RCT lane, bridged into replay-visible evidence metadata while redacting raw UID, challenge, CMAC, and key material from public projections.\n- **Operator-readable verification surface**: versioned `/api/v1/verification/*` endpoints plus TypeScript UI surfaces for queue, audit trail, asset forensics, replay, and runbook lookup.\n\nKey architecture references:\n\n- [Architecture overview](docs/architecture/overview/architecture.md)\n- [Agent Action Gateway contract](docs/development/agent_action_gateway_contract.md)\n- [Agentic delegation control plane](docs/development/agentic_delegation_control_plane.md)\n- [ExecutionToken lifecycle management](docs/development/execution_token_lifecycle_management.md)\n- [Policy gate matrix](docs/development/policy_gate_matrix.md)\n- [Hardware-anchored telemetry MVP contract](docs/development/hardware_anchored_telemetry_mvp_contract.md)\n- [ADR 0011: Benchmark-Gated Authorization Graph Engine Evolution](docs/architecture/adr/adr-0011-benchmark-gated-authz-graph-engine-evolution.md)\n- [Authz graph engine evolution plan](docs/development/authz_graph_engine_evolution_plan.md)\n- [ADR 0004: Coordinator-Embedded RESULT_VERIFIER](docs/architecture/adr/adr-0004-result-verifier-runtime.md)\n- [ADR 0005: Replayable Evidence for Governed State Transitions](docs/architecture/adr/adr-0005-replayable-evidence-governed-state-transitions.md)\n\n## Operator Verification Console\n\nSeedCore exposes a four-screen TypeScript operator surface backed by the verification API. The goal is to make cryptographic and policy outcomes legible without weakening the proof boundary.\n\n| Screen | Purpose | Backing surface |\n| --- | --- | --- |\n| Screen 1: Anomaly-first queue | Filter by status and prefixes such as `envelope:`, `approval:`, and `request:` | `/api/v1/verification/transfers/queue`, operator `/queue` |\n| Screen 2: Side-by-side audit trail | Compare transaction request, PDP authority, and physical closure | `/api/v1/verification/transfers/review` and audit-trail endpoints |\n| Screen 3: Asset forensics | Inspect custody state, telemetry refs, signer provenance, and transition receipts | `/api/v1/verification/assets/forensics` |\n| Screen 4: Replay and verification | Show replay detail, failure reasons, and runbook lookup links | `/api/v1/verification/workflows/{workflow_id}/verification-detail`, `/replay`, `/runbook/lookup` |\n\nThe operator console also provides a deterministic legibility layer: case verdicts, trust-gap counts, missing prerequisites, and runbook links derived from structured verification payloads.\n\n## Architecture at a Glance\n\nSeedCore is designed as a distributed execution fabric rather than a single-model application.\n\n| Layer | Role |\n| --- | --- |\n| Ray Serve and Ray Actors | Long-lived accountable actors, service orchestration, and distributed runtime behavior |\n| Postgres | Durable audit rows, verifier jobs, evidence state, and transaction records |\n| Redis | Token revocation, emergency cutoff propagation, and hot-path runtime support |\n| Neo4j | Graph-backed policy and authorization relationships |\n| Rust `seedcore-verify` | Offline and embedded proof-kernel verification paths |\n| TypeScript verification apps | Operator console, proof surface, and verification API |\n\nThe governed state transition is:\n\n```text\nEvent -> AI advisory plan -> Agent -> ActionIntent -> PDP\n  -> ExecutionToken or PolicyDeny\n  -> Actuator / edge path\n  -> EvidenceBundle and transition receipts\n  -> Replay / RESULT_VERIFIER\n  -> verified, rejected, review_required, or quarantined state\n```\n\n## Quick Start\n\n### Host-Mode Local Runtime\n\nFor macOS or laptop development, use the host-mode helpers in [deploy/local/README.md](deploy/local/README.md). They avoid the full Kind/Kubernetes footprint and are the best path for routine bring-up.\n\nPrerequisites:\n\n- PostgreSQL 17\n- Redis\n- Python virtual environment with project dependencies installed\n\nTypical startup:\n\n```bash\nbrew services start postgresql@17\nbrew services start redis\n\nPGUSER=$(whoami) bash deploy/local/init-full-db-direct.sh\n\nbash deploy/local/run-api.sh\nbash deploy/local/run-hal.sh\nbash deploy/local/run-task-stack.sh start\n```\n\nLocal endpoints:\n\n- API ingress: `http://127.0.0.1:8002`\n- HAL bridge: `http://127.0.0.1:8003`\n- Ray Serve / actor apps: `http://127.0.0.1:8000`\n- Live API docs: `http://127.0.0.1:8002/docs`\n\nFocused host verification:\n\n```bash\nbash scripts/host/verify_authz_graph_rfc_phases.sh\nbash scripts/host/verify_q2_verification_contracts.sh\n```\n\n### Kind + Kubernetes\n\nPrerequisites: `kubectl`, `kind`, `helm`, Docker, `envsubst` (macOS: `gettext`), and enough local resources for the cluster.\n\n```bash\ncp docker/env.example docker/.env\n./deploy/deploy-all.sh\n./deploy/port-forward.sh\n```\n\nUseful deployment flags include `--skip-build`, `--skip-hal`, `--skip-ingress`, `--worker-replicas N`, and `--deploy-verification-api`.\n\nVerify the core runtime after port-forwarding:\n\n```bash\ncurl http://localhost:8002/health\ncurl http://localhost:8002/readyz\ncurl http://localhost:8002/api/v1/pdp/hot-path/status\ncurl http://localhost:8002/api/v1/pdp/hot-path/metrics\n```\n\n### Rust Proof Kernel and TypeScript Surfaces\n\n```bash\ncargo test --workspace --no-default-features --manifest-path rust/Cargo.toml\ncargo build -p seedcore-verify --manifest-path rust/Cargo.toml\n\nnpm --prefix ts install\nnpm --prefix ts run typecheck\nnpm --prefix ts run build\n\nnpm --prefix ts run serve:verification-api    # http://127.0.0.1:7071\nnpm --prefix ts run serve:proof-surface       # http://127.0.0.1:7072\nnpm --prefix ts run serve:operator-console    # http://127.0.0.1:7073\n```\n\nOffline transfer proof example:\n\n```bash\ncargo run -q --manifest-path rust/Cargo.toml -p seedcore-verify -- \\\n  summarize-transfer --dir rust/fixtures/transfers/allow_case\n```\n\n### Gemini CLI Extension\n\nSeedCore ships a Gemini CLI extension scaffold that exposes read-only `seedcore.*` MCP tools. Bring up the runtime first, then install the extension:\n\n```bash\ngemini extensions install .\n```\n\nConfirm tools with `/extensions list`. For details, see [GEMINI.md](GEMINI.md), [gemini-tools.md](skills/using-seedcore/references/gemini-tools.md), and [gemini-troubleshooting.md](skills/using-seedcore/references/gemini-troubleshooting.md).\n\n## Testing\n\n```bash\n.venv/bin/pytest\nnpm --prefix ts run test\ncargo test --workspace --no-default-features --manifest-path rust/Cargo.toml\n```\n\nThe CI workflow is defined in [.github/workflows/unit-tests.yml](.github/workflows/unit-tests.yml).\n\n## License\n\nSeedCore is licensed under the Apache-2.0 License. See [LICENSE](LICENSE).\n",
  "bytes": 15672,
  "sha": "fa7c674e43fa8e6d22736a0f86e7688afa86d162a98e8e045b2d856008afe0a3",
  "repo_slug": "neilli/seedcore",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/plg_neilli_seedcore_44e1db16/readme"
}