Blueprint Schema Reference

Canonical Blueprint semantics are defined in ACGP-3: Blueprints, Traces & Evaluation.

Validation boundary JSON Schema validates structural shape. Runtime and SDK validation enforce semantic rules such as metric-weight totals, threshold consistency, and other cross-field invariants required for conformance.

---

Canonical Top-Level Shape

artifact_type: acgp.blueprint
schema_version: "2.0.0"
id: finance/refunds@2.0
version: "2.0.0"
title: "Refund policy"
description: "Refund policy for customer support operations"
base:
  ref: finance/base@2.0
applicability:
  governance_tiers: [GT-2, GT-3]
  tools: ["issue_refund"]
tripwires: []
checks: []
intervention_policy:
  thresholds:
    ok: 0.25
    nudge: 0.40
    escalate: 0.55
    # Risk > escalate → block (implicit; halt is tripwire-only)
evidence_policy:
  require_citations: true
trust_policy:
  enabled: true
  accumulation:
    ok: 0.0
    flag: 0.1
    nudge: 0.5
    escalate: 1.0
    block: 2.0
    halt: 5.0
  decay:
    decay_fraction: 0.05
    period_hours: 24
    min_debt: 0.0
  thresholds:
    elevated_monitoring: 1.0
    restricted_mode: 3.0
    re_tiering_review: 5.0
extensions:
  required: []
  optional: []
annotations:
  owner: support-governance
fixtures: []

---

Top-Level Fields

Field	Type	Required	Description	Source
artifact_type	string	Yes	Source-artifact discriminator. Value: acgp.blueprint	ACGP-3 / schema
schema_version	string	Yes	Schema version for the canonical source artifact	ACGP-3 / schema
id	string	Yes	Unique blueprint identifier	ACGP-3 / schema
version	string	Yes	Semantic version for blueprint artifact	ACGP-3 / schema
title	string	Yes	Human-readable policy title	ACGP-3 / schema
description	string	Yes	Purpose summary	ACGP-3 / schema
base	object	No	Parent source blueprint reference and optional digest pin	ACGP-3 / schema
applicability	object	No	Activation constraints by context	ACGP-3 / schema
tripwires	array	No	Safety constraints evaluated before checks	ACGP-3 / schema
checks	array	Yes	Canonical runtime checks using kind: rule | metric	ACGP-3 / schema
intervention_policy	object	Yes	Threshold mapping from evaluation result to intervention	ACGP-3 / schema
evidence_policy	object	No	Grounding/citation requirements	ACGP-3 / schema
trust_policy	object	No	Accumulation, decay, and threshold config for trust tracking	ACGP-3 / schema
extensions	object	No	Required/optional extension descriptors	ACGP-3 / schema
annotations	object	No	Non-normative annotations	ACGP-3 / schema
fixtures	array	No	Embedded policy fixtures for expected outcomes	ACGP-3 / schema

---

Key Nested Blocks

base

Field	Type	Required	Notes
ref	string	Yes	Parent source blueprint reference
digest	string	No	Optional content pin for deterministic inheritance

applicability

Field	Type	Required	Notes
governance_tiers	array[string]	No	Governance Tier values where the blueprint applies
tools	array[string]	No	Tool/action filters
domains	array[string]	No	Domain constraints
out_of_scope_behavior	enum	No	allow, block, or escalate

tripwires[]

Field	Type	Required	Notes
id	string	Yes	Unique tripwire id
when	object	No	Hook/tool match criteria
condition	string	Yes	Expression evaluated at runtime
on_fail.decision	enum	Yes	block / halt / etc. per policy semantics
on_fail.reason	string	Yes	Human-readable rationale

Tripwire semantics are normative in ACGP-4.

checks[]

Field	Type	Required	Notes
id	string	Yes	Check identifier
kind	enum	Yes	rule or metric
when	object	No	Evaluation hook
condition	string	Rule only	Deterministic rule expression
on_fail	object	Rule only	Direct fail mapping for rule checks
flag	boolean	Rule only	Orthogonal flag marker for rule checks
metric.name	string	Metric only	Metric identifier
metric.weight	number	Metric only	Weight contribution to aggregate evaluation
metric.evaluator.kind	enum	Metric only	rule-based, cognitive-evaluator, source-match, pattern-match, hybrid
metric.evaluator.args	object	Metric only	Evaluator-specific arguments

Mixed check shapes are invalid. A check with kind: rule cannot also declare metric, and a check with kind: metric cannot declare rule-only fields.

intervention_policy

All threshold values are in risk-score space (0.0 = perfect, 1.0 = worst).

Field	Type	Required	Notes
thresholds.ok	number	Yes	Max risk for ok
thresholds.nudge	number	Yes	Max risk for nudge
thresholds.escalate	number	Yes	Max risk for escalate

Only three threshold keys exist. Risk above escalate maps to the block intervention implicitly. halt is tripwire-driven and MUST NOT be emitted by threshold mapping alone.

evidence_policy

Field	Type	Required	Notes
require_citations	bool	No	Require source references
certified_only	bool	No	Restrict to certified sources
min_sources	integer	No	Minimum number of sources

trust_policy

Field	Type	Required	Notes
enabled	bool	Yes	Enable/disable trust tracking
accumulation	object	Yes	Per-intervention debt amounts (ok, flag, nudge, escalate, block, halt)
decay.decay_fraction	number	Yes	Fraction of debt removed per decay period (e.g., 0.05 = 5% removed).
decay.period_hours	number	Yes	Hours per decay cycle
decay.min_debt	number	Yes	Floor value after decay
thresholds.elevated_monitoring	number	Yes	Debt level triggering elevated monitoring
thresholds.restricted_mode	number	Yes	Debt level triggering restricted mode
thresholds.re_tiering_review	number	Yes	Debt level triggering Governance Tier review

fixtures[]

Field	Type	Required	Notes
id	string	Yes	Fixture identifier
input	object	Yes	Embedded trace/action fragment or test input
expected.primary_decision	enum	No	Expected primary decision (ok, nudge, escalate, block, halt; flag is orthogonal and not valid here)
expected.flags	array[string]	No	Expected flags
expected.tripwire_ids	array[string]	No	Expected tripwires
expected.evidence_outcome	string	No	Expected evidence result

---

Merge Semantics (base Resolution)

When base is present, effective policy is computed by resolving the parent source blueprint and compiling a resolved blueprint artifact.

Field	Merge Rule
id, version, title, description	Always child-defined
base	Used only for resolution lineage; not copied as a mutable scalar override
annotations	Child replaces parent entirely
applicability	Explicit child override rules; no implicit merge
tripwires	Append; if child reuses a parent tripwire.id, child overrides that id
checks	Append; if child reuses a parent check.id, child overrides that id
intervention_policy.thresholds	Child overrides parent per key
evidence_policy	Child overrides parent per key
trust_policy	Child overrides parent per key
extensions.required	Append; if child reuses a parent extension id, child overrides that id
extensions.optional	Append; if child reuses a parent extension id, child overrides that id

This merge table is normative and matches ACGP-3 base-resolution semantics.

---

Minimal Canonical Example

id: support/basic@1.0
artifact_type: acgp.blueprint
schema_version: "2.0.0"
version: "2.0.0"
title: "Basic support safeguards"
description: "Basic support safeguards"
tripwires:
  - id: no_pii_leak
    when:
      hook: output
    condition: "contains_pii(output.text)"
    on_fail:
      decision: block
      reason: "PII leakage detected"
checks:
  - id: reasoning_quality
    kind: metric
    when:
      hook: output
    metric:
      name: reasoning_quality
      weight: 0.25
      evaluator:
        kind: rule-based
        args:
          mode: all
          rules:
            - id: reasoning_present
              field: reasoning
              operator: exists
intervention_policy:
  thresholds:
    ok: 0.25
    nudge: 0.40
    escalate: 0.55
    # Risk > escalate → block (implicit; halt is tripwire-only)

---

Explicit Removals

Blueprint removes these fields from blueprint core:

• name
• ctq
• performance_budget
• fallback_behavior
• metadata
• raw inherits

Runtime-budget concerns now belong to Runtime Governance Contracts rather than blueprint core.

---

ACGP-3 Normative Spec Tripwire Semantics Error Codes API Reference