ActionCharter

A governed execution harness for AI agents using professional tools.

ActionCharter lets models interpret requests and propose work without giving
them unrestricted authority over shells, databases, filesystems, credentials,
or production systems. Deterministic software validates the proposal, binds
approval to its exact scope, dispatches only allowlisted operations, verifies
the resulting state, and preserves tamper-evident evidence.

Models propose; deterministic software authorizes, executes, validates,
and records evidence.

The current reference implementation applies this architecture to geospatial
data with GeoPandas, GDAL, rasterio, PostGIS, and GeoServer-oriented workflows.
GIS is the first reference domain, not the architectural limit.

ActionCharter is an alpha research and pilot implementation. It is not yet a
hardened multi-user production control plane.

Why ActionCharter?

Giving a model access to a powerful tool is easy. The harder problem is proving
that an AI-assisted operation:

1. used the correct input;
2. selected an allowed operation;
3. remained inside an explicitly bounded scope;
4. received approval for the exact consequential steps;
5. executed only what was approved;
6. produced a valid result;
7. was independently verified; and
8. left evidence that can be inspected later.

Generated text never becomes authority merely because a model generated it.
ActionCharter turns an uncertain proposal into a chain of typed, digest-bound,
and independently checkable artifacts.

Governed execution flow

flowchart TD
    A["User request"] --> B["Planner proposal"]
    B --> C["Schema and policy validation"]
    C --> D["Digest-bound plan"]
    D --> E["Human approval"]
    E --> F["Allowlisted execution"]
    F --> G["Deterministic validation"]
    G --> H["Independent verification"]
    H --> I["Immutable evidence and release"]
    C -->|Rejected| X["Fail closed"]
    E -->|Denied or expired| X
    G -->|Invalid result| X
    H -->|State mismatch| X

For consequential mutations, rollback is another governed operation. It
requires its own deterministic plan, exact approval, transactional execution,
and independent verification; it is not an emergency bypass.

Agents and authority

Planner, Executor, and Critic are intentionally separated. The Planner and
Critic may use the same local model runtime, but they receive different
contexts and permissions. The Executor has no model authority. Professional
tools and credentials remain behind controlled adapters and the internal MCP
boundary.

flowchart TD
    U["User / Operator"] --> P["Planner"]
    P --> G["Deterministic governance layer"]
    U --> A["Exact human approval"]
    A --> G
    G --> E["Executor"]
    E --> T["Allowlisted adapters / MCP"]
    T --> S["GIS, PostGIS, filesystem"]
    S --> V["Independent verifier"]
    V --> R["Evidence and release"]
    S --> C["Critic"]
    C --> R
    M["Local model runtime"] --> P
    M --> C

The Builder explores generated extensions under a separate lifecycle:
candidate generation, bounded materialization, offline tests, review,
digest-bound promotion, activation, and post-activation verification. Generated
code remains untrusted until those deterministic controls succeed.

Complete PostGIS reference lifecycle

Checkpoints 15A–15K provide the strongest end-to-end demonstration of the
governance model:

flowchart TD
    A["15A Inspect"] --> B["15B Compare"]
    B --> C["15C Assess"]
    C --> D["15D Plan promotion"]
    D --> E["15E Approve promotion"]
    E --> F["15F Execute promotion"]
    F --> G["15G Verify promotion"]
    G --> H["15H Plan rollback"]
    H --> I["15I Approve rollback"]
    I --> J["15J Execute rollback"]
    J --> K["15K Verify rollback"]

The inspection, comparison, and assessment stages are read-only and accept no
arbitrary SQL. Promotion and rollback execute only fixed, approved relation
renames inside serializable transactions. Separate verifiers reload the exact
plan, approval, and execution evidence and inspect PostGIS through independent
read-only transactions.

Representative commands:

geoagent inspect-postgis-table --schema agent_sandbox --table sample_points --pretty

geoagent compare-postgis-tables \
  --reference-schema agent_sandbox --reference-table current_layer \
  --candidate-schema agent_sandbox --candidate-table candidate_layer --pretty

geoagent assess-postgis-change \
  --reference-schema agent_sandbox --reference-table current_layer \
  --candidate-schema agent_sandbox --candidate-table candidate_layer --pretty

The remaining lifecycle is exposed through plan-postgis-promotion,
record-postgis-promotion-approval, execute-postgis-promotion,
verify-postgis-promotion, plan-postgis-rollback,
record-postgis-rollback-approval, execute-postgis-rollback, and
verify-postgis-rollback.

Implemented capabilities

Pilot demonstration

Checkpoint 14F connects proposal, deterministic compilation, human approval,
PostGIS execution, validation, operational history, Critic evidence,
authoritative release inspection, and Snakemake replay.

Its first gate is read-only and deterministic:

make checkpoint14f-readiness

It verifies a clean vector control, an invalid-geometry case, the contract
identity, and the exact workflow-input digest. It does not call a model, create
approval, execute a workflow, modify data, or create a release. See the
Checkpoint 14F demonstration for the
complete walkthrough.

Quick start

Requirements

• Linux or WSL2;
• Python 3.11 or newer;
• Docker Engine with Compose v2 for containerized boundaries;
• optional local Ollama-compatible endpoint for Planner, Builder, and Critic;
• optional externally managed PostGIS for database workflows.

The primary development environment is Ubuntu 24.04 LTS under WSL2. Hosted
CI exercises the offline suite and container contracts on Ubuntu. Other modern
Linux environments are expected to work but are not tested to the same level.

Offline unit tests and read-only fixture checks do not require model or
database credentials.

Install and test

git clone https://github.com/wanggiya/action-charter.git
cd action-charter
make install
make test

Run two read-only checks:

make inspect
make checkpoint14f-readiness

Validate and build the container topology:

make config
make build

Copy .env.example to .env only when configuring local services. Never
commit .env, credentials, private datasets, or generated operational
evidence.

Local model configuration

ActionCharter uses an OpenAI-compatible chat-completions interface and is
developed against a shared local Ollama runtime:

MODEL_PROVIDER=ollama
MODEL_BASE_URL=http://host.docker.internal:11434/v1
MODEL_NAME=qwen3:8b
MODEL_TIMEOUT_SECONDS=120

The model is used for constrained interpretation and assessment. It does not
receive PostGIS credentials or determine deterministic success.

Security model

Core invariants include:

• model output is always untrusted input;
• ENABLE_WRITE_TOOLS=false is the safe default;
• no interface accepts unrestricted shell commands or arbitrary SQL;
• approvals bind exact artifact identities and explicit consequential steps;
• trusted inputs and registries remain read-only at execution boundaries;
• approved paths must remain under bounded roots and symlinks fail closed;
• credentials are excluded from prompts, results, traces, and reports;
• generated code is tested inside an isolated, network-disabled workspace;
• independent deterministic verification—not model confidence—is the success gate;
• incomplete or inconsistent evidence withholds authoritative status.

Read SECURITY.md and the
runtime boundaries before deploying or
extending an execution path.

Repository guide

Detailed project records:

• architecture;
• current implementation status;
• project summary;
• product roadmap;
• accepted architectural decisions;
• dataset catalog;
• skills index;
• changelog.

Current scope and non-goals

ActionCharter demonstrates a complete governed PostGIS mutation and rollback
lifecycle, but remains a single-operator alpha rather than a production control
plane. Production authentication, multi-user authorization, strict network
egress enforcement, broader domain adapters, and a guided interface remain
future work.

The project deliberately does not compete by exposing the largest possible
tool catalog. Its focus is the controlled path from uncertain intent to
validated, inspectable, reversible, and reproducible action.

Compatibility

The public project and Python distribution are named ActionCharter. The
initial 0.9.x releases retain the geoagent_harness Python package and the
geoagent and geoagent-mcp commands. Existing evidence fields, Compose
service names, and established internal GeoAgent* types also remain
compatibility interfaces.

A future namespace migration requires a separately reviewed compatibility
plan; it is not part of the public-project rename.

Contributing

Contributions are welcome when they preserve ActionCharter's trust boundaries.
Read CONTRIBUTING.md before opening a pull request. Report
vulnerabilities through the private process in SECURITY.md, not
through a public issue.

Citation and license

ActionCharter was created by Jay Qi. Citation metadata is available in
CITATION.cff.

Copyright 2026 Jay Qi. Licensed under the Apache License, Version 2.0. See
LICENSE and NOTICE.