{
  "$schema": "https://schemas.zen-mesh.io/ai-idempotency-retry.schema.json",
  "schema_version": "1.0",
  "generated_at": "2026-07-14T12:11:00Z",
  "source_commit": "a399d87452317d91843521c9bd4a0fde61e9075e",
  "source_repository": "git@github.com:zenmesh/docs.git",
  "note": "18 operations. Human-readable matrix has 22 entries because update/delete/apply/disable/enable are expanded per resource type (Endpoint, Target, Flow) for easy lookup. Machine-readable projection groups these by operation type.",
  "operations": [
    {
      "operation_id": "create-endpoint",
      "operation": "create Endpoint",
      "idempotency": "CONDITIONALLY_IDEMPOTENT",
      "key_supported": true,
      "key_scope": "per-request, per-tenant",
      "key_retention": "24h",
      "repeated_request_result": "Same key + same body returns original result. Same key + different body returns 409 Conflict.",
      "concurrent_request_behavior": "No protection \u2014 idempotency keys do not prevent concurrent requests; use application-level locking if needed",
      "retry_owner": "caller (client)",
      "retryable_errors": "network timeout, 429 rate_limited, 5xx server errors",
      "permanent_errors": "4xx (except 429): validation_error, unauthorized, forbidden, not_found",
      "evidence_behavior": "Returns endpoint_id and operation_receipt on success",
      "implementation_status": "IMPLEMENTED_VERIFIED",
      "verification_status": "WIRED_SANDBOX"
    },
    {
      "operation_id": "create-target",
      "operation": "create Target",
      "idempotency": "CONDITIONALLY_IDEMPOTENT",
      "key_supported": true,
      "key_scope": "per-request, per-tenant",
      "key_retention": "24h",
      "repeated_request_result": "Same key + same body returns original result. Same key + different body returns 409 Conflict.",
      "concurrent_request_behavior": "No protection \u2014 idempotency keys do not prevent concurrent requests",
      "retry_owner": "caller (client)",
      "retryable_errors": "network timeout, 429 rate_limited, 5xx server errors",
      "permanent_errors": "4xx (except 429): validation_error, unauthorized, forbidden, not_found",
      "evidence_behavior": "Returns target_id and operation_receipt on success",
      "implementation_status": "IMPLEMENTED_VERIFIED",
      "verification_status": "WIRED_SANDBOX"
    },
    {
      "operation_id": "create-flow",
      "operation": "create Flow",
      "idempotency": "CONDITIONALLY_IDEMPOTENT",
      "key_supported": true,
      "key_scope": "per-request, per-tenant",
      "key_retention": "24h",
      "repeated_request_result": "Same key + same body returns original result. Same key + different body returns 409 Conflict.",
      "concurrent_request_behavior": "No protection \u2014 idempotency keys do not prevent concurrent requests",
      "retry_owner": "caller (client)",
      "retryable_errors": "network timeout, 429 rate_limited, 5xx server errors",
      "permanent_errors": "4xx (except 429): validation_error, unauthorized, forbidden, not_found",
      "evidence_behavior": "Returns flow_id and operation_receipt on success",
      "implementation_status": "IMPLEMENTED_VERIFIED",
      "verification_status": "WIRED_SANDBOX"
    },
    {
      "operation_id": "update",
      "operation": "update (Endpoint, Target, Flow)",
      "idempotency": "CONDITIONALLY_IDEMPOTENT",
      "key_supported": true,
      "key_scope": "per-request, per-tenant",
      "key_retention": "24h",
      "repeated_request_result": "Same key + same update body returns original result. Same key + different body returns 409 Conflict.",
      "concurrent_request_behavior": "No protection \u2014 idempotency keys do not prevent concurrent requests; conflicting updates possible",
      "retry_owner": "caller (client)",
      "retryable_errors": "network timeout, 429 rate_limited, 5xx server errors",
      "permanent_errors": "4xx (except 429): validation_error, unauthorized, forbidden, not_found, conflict",
      "evidence_behavior": "Returns updated resource and operation_receipt on success",
      "implementation_status": "IMPLEMENTED_VERIFIED",
      "verification_status": "WIRED_SANDBOX"
    },
    {
      "operation_id": "apply",
      "operation": "apply (activate configuration)",
      "idempotency": "IDEMPOTENT",
      "key_supported": true,
      "key_scope": "per-request, per-tenant",
      "key_retention": "24h",
      "repeated_request_result": "Re-applying same configuration returns same result; applies desired state",
      "concurrent_request_behavior": "No documented concurrent behavior",
      "retry_owner": "caller (client)",
      "retryable_errors": "network timeout, 429 rate_limited, 5xx server errors",
      "permanent_errors": "4xx (except 429): validation_error, unauthorized, forbidden",
      "evidence_behavior": "Returns apply_receipt and desired_state_hash on success",
      "implementation_status": "IMPLEMENTED_VERIFIED",
      "verification_status": "WIRED_SANDBOX"
    },
    {
      "operation_id": "disable",
      "operation": "disable resource",
      "idempotency": "IDEMPOTENT",
      "key_supported": true,
      "key_scope": "per-request, per-tenant",
      "key_retention": "24h",
      "repeated_request_result": "Disabling an already-disabled resource returns the original result",
      "concurrent_request_behavior": "No documented concurrent behavior",
      "retry_owner": "caller (client)",
      "retryable_errors": "network timeout, 429 rate_limited, 5xx server errors",
      "permanent_errors": "4xx (except 429): unauthorized, forbidden, not_found",
      "evidence_behavior": "Returns disable_receipt on success",
      "implementation_status": "IMPLEMENTED_VERIFIED",
      "verification_status": "WIRED_SANDBOX"
    },
    {
      "operation_id": "enable",
      "operation": "enable resource",
      "idempotency": "IDEMPOTENT",
      "key_supported": true,
      "key_scope": "per-request, per-tenant",
      "key_retention": "24h",
      "repeated_request_result": "Enabling an already-enabled resource returns the original result",
      "concurrent_request_behavior": "No documented concurrent behavior",
      "retry_owner": "caller (client)",
      "retryable_errors": "network timeout, 429 rate_limited, 5xx server errors",
      "permanent_errors": "4xx (except 429): unauthorized, forbidden, not_found",
      "evidence_behavior": "Returns enable_receipt on success",
      "implementation_status": "IMPLEMENTED_VERIFIED",
      "verification_status": "WIRED_SANDBOX"
    },
    {
      "operation_id": "retire",
      "operation": "retire resource with evidence",
      "idempotency": "NON_IDEMPOTENT",
      "key_supported": false,
      "key_scope": null,
      "key_retention": null,
      "repeated_request_result": "Retirement is not available. Use delete instead.",
      "concurrent_request_behavior": "Not applicable \u2014 operation not available",
      "retry_owner": "N/A",
      "retryable_errors": "N/A",
      "permanent_errors": "N/A",
      "evidence_behavior": "Not available \u2014 no evidence generated",
      "implementation_status": "PLANNED_V1_1",
      "verification_status": "NOT_SUPPORTED"
    },
    {
      "operation_id": "delete",
      "operation": "delete (Endpoint, Target, Flow)",
      "idempotency": "IDEMPOTENT",
      "key_supported": true,
      "key_scope": "per-request, per-tenant",
      "key_retention": "24h",
      "repeated_request_result": "Deleting an already-deleted resource returns the original result. DELETE is naturally idempotent.",
      "concurrent_request_behavior": "No documented concurrent behavior",
      "retry_owner": "caller (client)",
      "retryable_errors": "network timeout, 429 rate_limited, 5xx server errors",
      "permanent_errors": "4xx (except 429): unauthorized, forbidden, not_found",
      "evidence_behavior": "Returns deletion_receipt on success. Deletion is permanent \u2014 recovery requires recreating the resource.",
      "implementation_status": "IMPLEMENTED_VERIFIED",
      "verification_status": "WIRED_SANDBOX"
    },
    {
      "operation_id": "enrollment",
      "operation": "enrollment (edge plane / edge lite)",
      "idempotency": "CONDITIONALLY_IDEMPOTENT",
      "key_supported": false,
      "key_scope": null,
      "key_retention": null,
      "repeated_request_result": "Enrollment bundle is single-use and time-limited (30 min). If expired, generate a new bundle.",
      "concurrent_request_behavior": "Not documented",
      "retry_owner": "operator",
      "retryable_errors": "Bundle expired \u2014 regenerate from dashboard. Network timeout during enrollment.",
      "permanent_errors": "Enrollment rejected \u2014 verify bundle matches edge-plane ID. mTLS handshake failure \u2014 check certificates.",
      "evidence_behavior": "Enrollment bundle, plane identity issued by control plane",
      "implementation_status": "IMPLEMENTED_UNVERIFIED",
      "verification_status": "WIRED_SANDBOX"
    },
    {
      "operation_id": "credential-rotation",
      "operation": "credential rotation (HMAC, TLS, SVID)",
      "idempotency": "NON_IDEMPOTENT",
      "key_supported": false,
      "key_scope": null,
      "key_retention": null,
      "repeated_request_result": "Credential rotation is lifecycle-owner-specific (HMACKeyRotationController, cert-manager, etc.) and not a single API operation",
      "concurrent_request_behavior": "Not applicable \u2014 rotation is lifecycle-owner driven",
      "retry_owner": "system (HMACKeyRotationController for HMAC; cert-manager for TLS; JWKS service for JWK)",
      "retryable_errors": "cert-manager auto-retries renewal; HMAC rotation has 90-day grace period",
      "permanent_errors": "Not documented for each lifecycle owner",
      "evidence_behavior": "ZenLock provides custody/distribution/audit for secret material; rotation not performed by ZenLock",
      "implementation_status": "IMPLEMENTED_UNVERIFIED",
      "verification_status": "WIRED_SANDBOX"
    },
    {
      "operation_id": "event-submission",
      "operation": "event submission (submit webhook event)",
      "idempotency": "CONDITIONALLY_IDEMPOTENT",
      "key_supported": true,
      "key_scope": "per-event, per-tenant",
      "key_retention": "24h (deduplication window)",
      "repeated_request_result": "Idempotent within deduplication window. Same key within window is recognized as duplicate.",
      "concurrent_request_behavior": "Not documented",
      "retry_owner": "system (data plane automatic retry)",
      "retryable_errors": "Transient: network timeout, connection refused, rate limit. Undetermined: timeout without response.",
      "permanent_errors": "Invalid destination, authentication failure, provider verification failure",
      "evidence_behavior": "Returns event_id and delivery_attempts. Every delivery attempt recorded with outcome, timestamps, cryptographic integrity proofs.",
      "implementation_status": "IMPLEMENTED_VERIFIED",
      "verification_status": "WIRED_SANDBOX"
    },
    {
      "operation_id": "replay",
      "operation": "replay events from DLQ or delivery history",
      "idempotency": "CONDITIONALLY_IDEMPOTENT",
      "key_supported": true,
      "key_scope": "per-replay-request, per-tenant",
      "key_retention": "24h",
      "repeated_request_result": "Replay is idempotent \u2014 same replay request returns same result. However, replaying the same event range may produce duplicates.",
      "concurrent_request_behavior": "Not documented",
      "retry_owner": "operator (manual initiation); then system (delivery retry)",
      "retryable_errors": "N/A (initiation is an API call \u2014 standard API retry errors apply)",
      "permanent_errors": "Retained payload unavailable (retention exceeded), insufficient scope, delivery not found",
      "evidence_behavior": "Returns replay_receipt and replayed_event_ids. Each replay attempt recorded with new delivery attempt ID.",
      "implementation_status": "IMPLEMENTED_VERIFIED",
      "verification_status": "WIRED_SANDBOX"
    },
    {
      "operation_id": "delivery-retry",
      "operation": "delivery retry (manual retry of failed delivery)",
      "idempotency": "IDEMPOTENT",
      "key_supported": true,
      "key_scope": "per-retry-request, per-tenant",
      "key_retention": "24h",
      "repeated_request_result": "Retry is idempotent \u2014 calling retry on an already-retried delivery does not create duplicate deliveries",
      "concurrent_request_behavior": "Not documented",
      "retry_owner": "operator (manual retry)",
      "retryable_errors": "Standard API retry errors: network timeout, rate limit",
      "permanent_errors": "4xx (except 429): insufficient scope, event not found, idempotency conflict",
      "evidence_behavior": "Returns retry_receipt with delivery_id and status. Retry re-uses original delivery \u2014 does not re-ingest from source.",
      "implementation_status": "IMPLEMENTED_VERIFIED",
      "verification_status": "WIRED_SANDBOX"
    },
    {
      "operation_id": "certificate-rotation",
      "operation": "certificate rotation (TLS certificates)",
      "idempotency": "NON_IDEMPOTENT",
      "key_supported": false,
      "key_scope": null,
      "key_retention": null,
      "repeated_request_result": "Certificate rotation uses cert-manager auto-renewal with 24h default. Manual rotation is supported but not idempotent.",
      "concurrent_request_behavior": "Not applicable \u2014 rotation is lifecycle-owner driven",
      "retry_owner": "system (cert-manager)",
      "retryable_errors": "cert-manager auto-retries renewal",
      "permanent_errors": "Not documented \u2014 certificate expiry behavior is UNRESOLVED",
      "evidence_behavior": "Certificate bundle evidence via ZenLock audit trail",
      "implementation_status": "MANUAL_IN_V1_1",
      "verification_status": "REQUIRES_DOCUMENTATION"
    },
    {
      "operation_id": "inconsistent-state-recovery",
      "operation": "inconsistent-state recovery",
      "idempotency": "NON_IDEMPOTENT",
      "key_supported": false,
      "key_scope": null,
      "key_retention": null,
      "repeated_request_result": "No automated recovery \u2014 reapply is the recommended approach. NOT_SUPPORTED in v1.1.",
      "concurrent_request_behavior": "Not applicable \u2014 operation not available",
      "retry_owner": "manual (operator)",
      "retryable_errors": "N/A",
      "permanent_errors": "N/A",
      "evidence_behavior": "Reapply generates new evidence; divergence detection not automated",
      "implementation_status": "MANUAL_IN_V1_1",
      "verification_status": "NOT_SUPPORTED"
    },
    {
      "operation_id": "mcp-write",
      "operation": "MCP write operation",
      "idempotency": "CONDITIONALLY_IDEMPOTENT",
      "key_supported": true,
      "key_scope": "per-mcp-write, per-tenant",
      "key_retention": "24h",
      "repeated_request_result": "Conditionally idempotent \u2014 depends on underlying API operation",
      "concurrent_request_behavior": "Not documented",
      "retry_owner": "caller (MCP client)",
      "retryable_errors": "Network timeout, rate limit",
      "permanent_errors": "4xx: unauthorized, forbidden, not_found. Disabled by default \u2014 explicit object/action permission required.",
      "evidence_behavior": "Returns mcp_write_receipt on success",
      "implementation_status": "IMPLEMENTED_UNVERIFIED",
      "verification_status": "WIRED_SANDBOX"
    },
    {
      "operation_id": "future-git-reconciliation",
      "operation": "future Git reconciliation (GitOps)",
      "idempotency": "UNRESOLVED",
      "key_supported": null,
      "key_scope": null,
      "key_retention": null,
      "repeated_request_result": "Not implemented \u2014 Git reconciliation is planned for v1.1. Idempotency model is not yet defined.",
      "concurrent_request_behavior": "Not implemented",
      "retry_owner": "UNRESOLVED",
      "retryable_errors": "UNRESOLVED",
      "permanent_errors": "UNRESOLVED",
      "evidence_behavior": "UNRESOLVED",
      "implementation_status": "PLANNED_V1_1",
      "verification_status": "NOT_SUPPORTED"
    }
  ],
  "canonical_source_commit": "a399d87452317d91843521c9bd4a0fde61e9075e",
  "artifact_commit": "a399d87452317d91843521c9bd4a0fde61e9075e",
  "generation_method": "hand-maintained JSON aligned with idempotency-retry matrix, FAQ, and API documentation",
  "implementation_status_semantics": "IMPLEMENTED_VERIFIED: retried and confirmed. IMPLEMENTED_UNVERIFIED: code exists, formal verification pending. MANUAL_IN_V1_1: operator-driven procedure available, no automation. PLANNED_V1_1: design complete, not yet implemented.",
  "verification_status_semantics": "WIRED_SANDBOX: verified in sandbox. REQUIRES_DOCUMENTATION: procedure documented but automated verification pending. NOT_SUPPORTED: not applicable or not implemented."
}