From 30e63d6cb58e4911442e3f8b21a197cad5a28915 Mon Sep 17 00:00:00 2001
From: Jon Chery <jchery@jccapital.xyz>
Date: Tue, 21 Jul 2026 14:19:44 +0000
Subject: [PATCH] docs(contracts): add elaborate example contracts with rich
 inputs

---ci---
phase: 5
milestone: v1.0
status: complete
---/ci---

Two reference contracts under contracts/examples/ demonstrating how
developers can use the open-ended inputs: map (D-021) to carry
environment + ownership + business context + deployment knobs +
operational flags. 29 keys each.

- contract-commodity-price-feed-prod.yaml: passing pipeline (POLICY_PASS,
  score 0.90, all 5 L1s applied)
- contract-regulatory-reporting-violation.yaml: Act 4 trigger
  (public-ingress: true -> POLICY_VIOLATION:PUBLIC_INGRESS -> score 0.40
  < 0.50 gate -> Dev rejects)

Both validated end-to-end: yaml load, policy_checker, confidence_signal,
mock_executor (passing contract only). state.json captures all 29 input
keys.
---
 .../contract-commodity-price-feed-prod.yaml   | 55 +++++++++++++++++++
 ...ntract-regulatory-reporting-violation.yaml | 55 +++++++++++++++++++
 2 files changed, 110 insertions(+)
 create mode 100644 contracts/examples/contract-commodity-price-feed-prod.yaml
 create mode 100644 contracts/examples/contract-regulatory-reporting-violation.yaml

diff --git a/contracts/examples/contract-commodity-price-feed-prod.yaml b/contracts/examples/contract-commodity-price-feed-prod.yaml
new file mode 100644
index 0000000..03b8af7
--- /dev/null
+++ b/contracts/examples/contract-commodity-price-feed-prod.yaml
@@ -0,0 +1,55 @@
+# Elaborate developer contract — energy trading price feed.
+#
+# Schema (D-021): stack + inputs (open-ended string map) + public-ingress.
+# The `stack` field MUST match an L2 folder name under modules/l2/.
+# The `inputs` map is free-form string values; these are L2-level params
+# that travel with the deployment into state.json and the audit trail.
+# The L1 input values are declared by the L2's manifest.yaml, not here.
+#
+# Commit this to acdl-contracts as contract.yaml to trigger the pipeline:
+#   git add contract.yaml && git commit -m "feat: deploy price feed (prod)" && git push
+
+stack: l2-commodity-price-feed
+
+inputs:
+  # --- Environment + ownership ---
+  environment: prod
+  owner: commodity-trading-platform-team
+  team: power-and-gas-desk
+  cost_center: CC-TRD-4471
+  change_ticket: CHG-2026-07-21-093
+
+  # --- Business context (rides into the audit timeline) ---
+  business_owner: kchen@jccapital.xyz
+  oncall_email: sre-commodity@example.com
+  sla_tier: T1
+  business_hours: "Mon-Fri 07:00-19:00 ET"
+  data_classification: internal
+
+  # --- Source feed contract (business-facing) ---
+  feed_vendor: Platts
+  feed_name: natural-gas-daily-settlement
+  feed_cadence: daily
+  feed_timezone: US/Eastern
+  symbols: "NG-WTI-HH,NG-HH-M,NG-PJM"
+  retry_policy: backoff-3x-15min
+  dead_letter_queue: commodity-price-dlq
+
+  # --- Deployment knobs (consumed by the pipeline; passed to L1s via L2 manifest) ---
+  replicas: "3"
+  cpu_request: "500m"
+  memory_request: "1Gi"
+  autoscale_min: "2"
+  autoscale_max: "8"
+  log_retention_days: "90"
+  archive_retention_days: "2555"
+
+  # --- Operational flags ---
+  enable_canary: "true"
+  canary_percentage: "10"
+  enable_pagerduty: "true"
+  enable_cost_alerts: "true"
+  cost_alert_threshold_usd: "500"
+
+# Policy-gated field. true -> POLICY_VIOLATION:PUBLIC_INGRESS -> confidence 0.40 < 0.50 -> Dev rejects (Act 4).
+public-ingress: false
\ No newline at end of file
diff --git a/contracts/examples/contract-regulatory-reporting-violation.yaml b/contracts/examples/contract-regulatory-reporting-violation.yaml
new file mode 100644
index 0000000..ec3dd95
--- /dev/null
+++ b/contracts/examples/contract-regulatory-reporting-violation.yaml
@@ -0,0 +1,55 @@
+# Elaborate developer contract — regulatory reporting (with policy violation).
+#
+# Same schema as the price-feed example, but with public-ingress: true,
+# which triggers Act 4: the policy_checker fails, the confidence_signal
+# drops to 0.40, the 0.50 gate halts the pipeline in Dev, and the
+# rejection appears on the evidence timeline.
+#
+# Commit this to acdl-contracts as contract.yaml to reproduce Act 4:
+#   git add contract.yaml && git commit -m "feat: deploy regulatory reporting" && git push
+
+stack: l2-regulatory-reporting
+
+inputs:
+  # --- Environment + ownership ---
+  environment: prod
+  owner: compliance-and-controls-team
+  team: regulatory-reporting-desk
+  cost_center: CC-CMP-9902
+  change_ticket: CHG-2026-07-21-118
+  business_owner: compliance@jccapital.xyz
+  oncall_email: sre-regulatory@example.com
+  sla_tier: T0
+  business_hours: "24x7"
+  data_classification: confidential
+
+  # --- Regulatory context ---
+  regulator: FERC
+  filing_frequency: monthly
+  filing_deadline_day_of_month: "15"
+  reporting_period: 2026-Q3
+  jurisdiction: US-Federal
+  legal_hold: "false"
+
+  # --- Deployment knobs ---
+  replicas: "2"
+  cpu_request: "1000m"
+  memory_request: "2Gi"
+  autoscale_min: "2"
+  autoscale_max: "4"
+  log_retention_days: "365"
+  archive_retention_days: "2555"
+  enable_encryption_at_rest: "true"
+  enable_kms_rotation: "true"
+
+  # --- Operational flags ---
+  enable_canary: "false"
+  enable_pagerduty: "true"
+  enable_cost_alerts: "true"
+  cost_alert_threshold_usd: "1000"
+
+# POLICY VIOLATION — this is the Act 4 trigger.
+# The policy_checker.py will emit: POLICY_VIOLATION:PUBLIC_INGRESS
+# The confidence_signal.py will return: {"score": 0.40, "reason": "POLICY_VIOLATION:PUBLIC_INGRESS"}
+# The 0.50 gate halts the pipeline in Dev; mock_executor never runs.
+public-ingress: true
\ No newline at end of file