Skip to content

How to Develop your own Cartridge

Jump to bottom
Pheonetic Coder edited this page Aug 17, 2025 · 3 revisions

How to Develop Your Own Cartridge (GCP V49 Flagship)

A Cartridge is a domain pack that supplies knowledge, metrics, legal constraints, risks, metamorphic relations, and policies for a given problem space. Cartridges plug into Exotics runner and are additive: the Cartridge API v49 is stable; fields are unchanged from earlier v49 and additions are safe.

At a glance

  • Contract: Runner API v49 & Cartridge API v49 are compatible; phases −1..16 and Gate_Signals.json schema are unchanged.

  • Runners can delegate micro-gates/metrics/policies to your cartridge at attach-time.

  • If tools or file I/O are missing, emit inline artifacts using BEGIN ARTIFACT … END ARTIFACT and keep INDEX.md/MANIFEST.json current.

1) Recommended repo layout

Runners/<Domain>/Cartridges/<CartridgeName>/
  ├─ Policies/                  # Rego policy modules for gates/refusals
  ├─ metamorphic/               # invariants/transforms JSON
  ├─ novelty/                   # SOTA baselines, benchmarks
  ├─ tests/                     # property/metamorphic/adversarial tests
  ├─ observability/             # <cartridge>_otel-plan.md
  ├─ Docs/                      # domain references, playbooks
  ├─ Rehydration_Test/          # script + status JSON
  ├─ MANIFEST.json              # cartridge manifest (see below)
  └─ cartridge.json             # Cartridge API object (v49)

Top-level GCP directories for Evidence, SBOM, provenance, etc., remain standard in Flagship V49.

2) Cartridge API (v49) — minimal example

cartridge.json

{
  "cartridge": {
    "domain": "Networking/LEO",
    "knowledge": ["canonical_terms", "glossary", "references"],
    "metrics": ["median_throughput", "p95_rtt", "jain_fairness"],
    "legal": ["export_rules", "spectrum_regs"],
    "risks": ["misallocation", "instability", "starvation"],
    "metamorphic_relations": [
      "unit_invariance",
      "reordering_robustness",
      "monotonicity_latency_budget"
    ],
    "policies": "BEGIN ARTIFACT:Policies/cart_domain.rego\n# ...\nEND ARTIFACT"
  }
}

Based on the Cartridge API (stable for V49).

3) How a cartridge plugs into a runner (flow)

flowchart LR
  A["Attach runner <X>"] --> B["Attach cartridge <Y>"]
  B --> C["Merge: agent_graph + memory_config"]
  C --> D["Apply cartridge policies + micro-gates"]
  D --> E["Run phases & gates"]
  E --> F["Export: XW bundle"]

Runners (e.g., Exotics) merge their agent graph/memory with the selected cartridge, then apply the cartridge’s refusal policy, micro-gates, metrics, and artifacts.

4) Policies (Rego) — refusal rules & gate checks

Create Rego modules in Policies/. Use deny-by-default with explicit allows for sensitive actions (tools, exports, disclosures).

Policies/cart_domain.rego (sketch)

package cart.domain

default allow := false


Example: forbid ungrounded claims on critical outputs


deny[msg] {
input.outputs[].type == "claim"
not input.outputs[].hasEvidence
msg := "Ungrounded claim without Evidence_Index ref"
}


Example: require invariants pass before proceed


deny[msg] {
input.metrics.metamorphic_pass_rate < 0.90
msg := "Metamorphic threshold not met"
}


allow {
not deny[_]
}

Rego is the policy language of Open Policy Agent (OPA); it decouples policy from application logic and evaluates structured JSON inputs. (Open Policy Agent) (Open Policy Agent)

5) Metamorphic & property-based tests

Place invariants/transforms in metamorphic/, and connect them to your test harness under tests/.

metamorphic/invariants.json

{
  "unit_invariance": "scale units → consistent result",
  "reordering_robustness": "shuffle inputs → same outcome class",
  "monotonicity_latency_budget": "latency increases not to exceed budget"
}

Flagship codex mandates metamorphic tests as first-class checks across runners; cartridges add their domain-specific invariants and transforms.

6) Novelty & SOTA

Track baselines and thresholds under novelty/ (e.g., sota_benchmarks.csv). Gate on novelty_score and comparisons.

Example targets (short)

Metric Target
novelty_score ≥ 0.40
metamorphic_pass_rate ≥ 0.90

(Each row maps to stable Flagship requirements.)

16) Gate UX & Decision Cards

Your cartridge gates participate in the Gate Decision Card flow (options, recommendation, confidence, cost/time, risks) and can be Human-Required. 

flowchart LR
  G["Gate"] --> D["Decision Card"]
  D -->|1 Proceed| P["Next"]
  D -->|2 Branch| B["Alternate"]
  D -->|3 Return| R["Rework"]
  D -->|4 End| X["Export"]

17) Standards & references (examples)

Use short pointers in your cartridge; store full links in Docs/ as needed.

Appendix A — Guardrail rationale codes (sample)

Keep rationale codes consistent across cartridges to ease triage.

  • LLM.JB-### — jailbreak/prompt-injection

  • MET.INV-### — metamorphic invariant violated

  • NOV.SOTA-### — novelty/SOTA threshold not met

  • POL.SEC-### — security policy violation

  • COM.LIC-### — license/legal failure
    (Flagship canonical taxonomy.)

Appendix B — Gate_Signals.json (stable shape)

{
  "phase": "P4",
  "status": "allow | deny | needs-human",
  "who": "Adversary",
  "why_code": "LLM.JB-002",
  "why_text": "Prompt conditioning escaped guard; patched policy added",
  "evidence": ["Evidence_Log/2025-08-17T14-10Z.md#L44"],
  "hashes": ["sha256:..."],
  "attestations": ["provenance/build.intoto.jsonl"]
}

(Stable schema; unchanged in V49.)

If you want, I can also generate a scaffold for a new cartridge (folders + starter files) and a GitHub Actions PR that wires the OPA/SBOM/provenance checks.

Clone this wiki locally