`.curd` Scripts & Plan Artifacts

CURD v0.7.1 intentionally separates script authoring from governed execution. This allows developers to easily prototype workflows while satisfying strict organizational audit trails.

.curd: The source format designed for human (and agent) authoring.
Compiled Plan Artifacts: The strictly governed execution contract.

Why Both Exist

.curd files are easy to write, readable, and reusable. Compiled plan artifacts, however, are stable. They carry bound arguments, explainability metadata, safeguards, profile constraints, and a complete snapshot of the runtime ceiling.

By splitting the two, local developers stay in readable scripts, while security teams can insist on inspectable, repeatable compiled execution artifacts.

Writing `.curd` Scripts

The .curd language provides a clean syntax for interacting with the Semantic Graph and the Shadow Workspace. It currently supports:

use profile ... and use session ...
arg (parameterized scripts)
let (variable assignment)
Multiline strings (for code patches)
Tool-call statements
sequence and atomic blocks
abort

Explainability Comments

Structured comments are parsed and preserved straight into compiled metadata:


# explain: tighten auth validation without changing the public entrypoint
# why: downstream callers depend on the current function name
# risk: auth and session modules are tightly connected

use session required

let patch = """
pub fn validate(token: &str) -> bool {
    !token.is_empty()
}
"""

atomic {
  edit uri="src/auth.rs::validate" action="upsert" code=$patch
  verify_impact strict=true
}

Script Arguments

Arguments let one source script emit multiple concrete plan artifacts based on inputs.


arg target_uri: string
arg strict: bool = true

let patch = """
pub fn alpha() {}
"""

edit uri=$target_uri action="upsert" code=$patch
verify_impact strict=$strict

The Script Lifecycle

1. Check

Run a preflight check without mutating anything. This compiles the script and reports resolved targets, graph-adjacent impact, conflict risk, session requirements, and suggested safeguards.


curd run check fix_auth.curd --target-uri src/lib.rs::alpha

2. Compile

Compile the script to emit a concrete plan artifact under .curd/plans/.


curd run compile fix_auth.curd --target-uri src/lib.rs::alpha

The compiled artifact contains the payload, source hash, source path, bound argument values, explainability metadata, and runtime snapshot.

3. Edit the Plan Artifact

You can interactively refine the compiled artifact defaults before executing it. This is where you might enforce stronger governance on an agent’s plan:


curd plan edit <plan-id>

You can tweak the profile, output limits, or retry limits per-node, ensuring the artifact fits the precise security posture required.

4. Execute

Mutating scripts or plans must run within an active workspace session.


# Start a new transaction
curd workspace begin
 
# Execute the script (or the compiled plan ID)
curd run fix_auth.curd
 
# Commit the shadow workspace to disk
curd workspace commit

(If the execution produces unexpected results, simply use curd workspace rollback to discard the changes).

.curd Scripts & Plan Artifacts