Crate agentstategraph_ffi

Expand description

C ABI for AgentStateGraph — opaque handle-based API.

All functions use opaque pointers and C strings. The caller is responsible for freeing returned strings with agentstategraph_free_string.

This crate produces a shared library (.so/.dylib/.dll) and static library (.a) that any language with C FFI can call.

Every extern "C" function in this crate takes raw pointers by design — they form the C ABI contract. Marking them unsafe fn would change that ABI and make every bindgen-generated header noisier. We validate pointer inputs inside each function instead (is_null checks, bounded CStr reads). The blanket allow below silences clippy on this pattern crate-wide.

Structs§

SgPolicyStore: Opaque handle to a PolicyStore.
SgRepo: Opaque handle to a Repository.
SgTaskStore: Opaque handle to a TaskStore.

Functions§

agentstategraph_blame: Blame — returns JSON string with blame entry.
agentstategraph_branch: Create a branch. Returns commit ID string.
agentstategraph_check_taint: Check the taint status for path given agent_id + confidence.
agentstategraph_delete: Delete a value at a path. Returns commit ID string.
agentstategraph_delete_branch: Delete a branch by name. Returns {"deleted": true|false} or {"error": "..."}. deleted=false means the ref didn’t exist.
agentstategraph_diff: Diff two refs. Returns JSON string of DiffOps.
agentstategraph_fork_namespace: Create another repository handle over the same storage, scoped to namespace. The returned handle has independent active session/epoch state and must be released with agentstategraph_free.
agentstategraph_free: Free a repository handle.
agentstategraph_free_string: Free a string returned by AgentStateGraph functions.
agentstategraph_get: Get a JSON value at a path. Returns a JSON string (caller must free).
agentstategraph_list_branches: List branches, optionally filtered by prefix. prefix may be NULL or an empty string for no filter. Returns a JSON array of {"name": String, "target": String} objects (target = commit id hex), or {"error": "..."} on failure.
agentstategraph_list_taints: List active taints / quarantines / watches. kind_or_null accepts “taint” | “quarantine” | “watch” or NULL to list all.
agentstategraph_log: Get commit log as JSON. Returns JSON array string.
agentstategraph_merge: Merge source into target. Returns commit ID or error JSON.
agentstategraph_migrate_check: Check the migration status of a repository. Returns a JSON report: {"status":"up_to_date","version":"0.4.0"}, "upgrade_available", "downgrade", "unversioned", "corrupt". target may be null to use the binary’s current SCHEMA_VERSION.
agentstategraph_migrate_run: Run migrations. mode is "apply" or "dry-run". Returns a JSON report describing each step.
agentstategraph_new_memory: Create a new in-memory AgentStateGraph repository.
agentstategraph_new_postgres: Create a new Postgres-backed AgentStateGraph repository.
agentstategraph_new_sqlite: Create a new SQLite-backed AgentStateGraph repository.
agentstategraph_policy_active: List currently-active (ratified and active_from <= now) policies. prefix_or_null filters by path prefix (NULL/empty = all). Returns JSON array.
agentstategraph_policy_check_tokens: List active policies whose triggers intersect tokens_json (a JSON array of strings). Binding-level helper mirroring the internal filter used by evaluate_change. Returns JSON array of policies.
agentstategraph_policy_evaluate: Authorization evaluation (POLICY_V1.md §5). situation_json is a flat {string: string} JSON object, or {"facts": {...}} wrapper. Returns JSON Decision.
agentstategraph_policy_evaluate_change: Change-proposal evaluation (POLICY_V1.md §22.2). proposal_json is a JSON ChangeProposal. Returns JSON Decision.
agentstategraph_policy_evaluate_change_scoped: Scoped change-proposal evaluator (0.7.5 §3b). See agentstategraph_policy_evaluate_scoped for tenant_filter semantics.
agentstategraph_policy_evaluate_scoped: Scoped evaluator (0.7.5 §3b). Variant of agentstategraph_policy_evaluate that accepts an optional tenant_filter. Pass NULL for no filter (equivalent to the non-scoped variant). Returns JSON Decision.
agentstategraph_policy_get: Fetch the active policy at path. Returns JSON policy object.
agentstategraph_policy_history: Walk the supersedes chain for path. Returns JSON array, oldest first through the current active version.
agentstategraph_policy_list: List policies whose path starts with prefix_or_null (NULL or empty = no filter). Returns JSON array of policies.
agentstategraph_policy_propose: Propose a new (unratified) policy. policy_json is a JSON object matching the Policy schema. Returns a JSON string "path@version" handle on success, or {"error": ...} JSON on failure.
agentstategraph_policy_ratify: Ratify an unratified proposal at path. Returns {"ok":true} on success, {"error": ...} on failure.
agentstategraph_policy_set_external_evaluator: Configure an external policy evaluator on the store (0.7.5 §4c).
agentstategraph_policy_sign: Sign the active policy at path. §2c of the 0.7.5-beta.1 plan.
agentstategraph_policy_store_free: Free a PolicyStore handle.
agentstategraph_policy_store_new: Create a new PolicyStore handle bound to the given repository, path prefix, and agent id. The returned pointer must be freed with agentstategraph_policy_store_free. The underlying repository is shared (refcounted); freeing the PolicyStore does NOT free the repository.
agentstategraph_policy_supersede: Replace the active policy at path with new_policy_json. Returns JSON "path@new_version" handle on success.
agentstategraph_policy_verify: Verify the signature on the active policy at path. §2c of the 0.7.5-beta.1 plan.
agentstategraph_quarantine_apply: Apply a quarantine. params_json: {"name","reason","severity","authorized_agents":[...],"expires","propagate","agent_id"}.
agentstategraph_quarantine_release: Release a quarantine. params_json shape matches taint_remove.
agentstategraph_repository_call: Invoke an advanced repository operation through the stable JSON ABI.
agentstategraph_repository_capabilities: Return the advanced repository API contract implemented by agentstategraph_repository_call. Keeping this contract data-driven gives native bindings one stable ABI entry point while still allowing their public APIs to remain strongly typed and idiomatic.
agentstategraph_set: Set a JSON value at a path. Returns commit ID string (caller must free).
agentstategraph_taint_apply: Apply a taint. params_json shape: {"name":"...","effect":"warn|block|review|isolate","reason":"...", "severity":"medium","expires":null,"propagate":true,"agent_id":"..."}. Returns JSON {"ok":true,"id":"<uuid>"} or {"error":"..."}.
agentstategraph_taint_remove: Remove a taint. params_json: {"name":"...","reason":"...","proof":null,"agent_id":"..."}.
agentstategraph_taskstore_abandon_task
agentstategraph_taskstore_add_task: Add a task. Arguments:
agentstategraph_taskstore_add_task_ex: Extended add_task that also threads the 0.6.0 Task extension fields through the FFI: payload_json (an arbitrary JSON value or NULL), parent_change (opaque string or NULL), on_complete_json (a JSON OnCompleteHook value or NULL — see agentstategraph-tasks::OnCompleteHook for the variant tags). Returns the Task as JSON or {"error": "..."}.
agentstategraph_taskstore_archive_plan
agentstategraph_taskstore_assign_task
agentstategraph_taskstore_complete_task: Complete a task. proof_kind is “commit” | “file” | “test” | “text”.
agentstategraph_taskstore_create_plan: Create a plan. Returns the Plan as JSON, or {"error": ...} on failure.
agentstategraph_taskstore_delete_plan
agentstategraph_taskstore_derived_status: Compute the derived (rollup) status of a parent task. Returns "pending" | "in_progress" | "done" | "abandoned" JSON-wrapped.
agentstategraph_taskstore_free: Free a TaskStore handle.
agentstategraph_taskstore_get_plan: Get a plan by name.
agentstategraph_taskstore_get_task
agentstategraph_taskstore_list_plans: List plans. Returns JSON array.
agentstategraph_taskstore_list_plans_by_status: List plans filtered by status. status is “active”, “completed”, “archived”, or null/empty for all. Returns JSON array.
agentstategraph_taskstore_list_tasks
agentstategraph_taskstore_new: Create a new TaskStore handle bound to the given repository, path prefix, and agent id. The returned pointer must be freed with agentstategraph_taskstore_free. The underlying repository is shared (refcounted); freeing the TaskStore does NOT free the repository.
agentstategraph_taskstore_next_task: Returns the next unblocked task as JSON, null if none, or error JSON.
agentstategraph_taskstore_next_task_for: Next task filtered by assignment. agent null for any; include_unassigned controls fallback to unassigned when an agent is specified.
agentstategraph_taskstore_set_blockers: Set blockers. blockers_json is a JSON string array (may be null or “[]”).
agentstategraph_taskstore_set_priority
agentstategraph_taskstore_set_title: Replace a task’s title; a blank title is refused.
agentstategraph_taskstore_start_task
agentstategraph_taskstore_task_ids
agentstategraph_taskstore_unassign_task
agentstategraph_watch_apply: Apply a watch. params_json: {"name","reason","metric","threshold","direction":"above|below", "check_interval_secs","expires","severity","propagate","agent_id"}.
agentstategraph_watch_remove: Remove a watch.