{
  "schema_version": "1.0",
  "baseline": "A-feature-flags-batch-4-readiness",
  "phase": "2b+ → 2c readiness",
  "updated_at": "2026-04-19",
  "owner": "session_a",
  "purpose_th": "Matrix ของ test vector ที่ harness จะใช้เทียบ file-backed vs db-backed · รวมการครอบคลุม auth mode × override scope × sensitive gating · ทุกแถวระบุ expected outcome",
  "purpose_en": "Matrix of test vectors the parity harness will run to verify file-backed and db-backed behave identically before cutover. Cross product of auth mode × override scope × sensitive gating × TTL state. Each vector defines inputs, expected enabled value, expected warnings, and which backing states must agree.",
  "honest_note": "Harness does NOT exist yet. This matrix defines the contract it must implement. Phase 2c implementation should build the harness to consume this JSON directly.",
  "required_coverage": {
    "auth_modes": ["verified", "decode-only", "dev-fallback", "anonymous"],
    "override_scopes": ["user_override", "tenant_override", "default"],
    "sensitive_paths": ["non_sensitive", "sensitive_valid_approval", "sensitive_expired_approval", "sensitive_missing_approval", "sensitive_auth_unverified"],
    "ttl_states": ["valid", "near-expiry", "expired", "stale", "not-applicable", "unknown"]
  },
  "vectors": [
    {
      "id": "PT-01",
      "coverage": ["auth:anonymous", "scope:default", "sensitive:non_sensitive"],
      "input": { "flag": "ff.wizard.interactive_draft", "user": null, "tenant": null, "auth_mode": "anonymous" },
      "expected": { "enabled": true, "source": "default", "warnings_set": [], "verified": false },
      "must_match_fields": ["enabled", "source", "warnings_set", "verified"]
    },
    {
      "id": "PT-02",
      "coverage": ["auth:dev-fallback", "scope:tenant_override", "sensitive:non_sensitive"],
      "input": { "flag": "ff.enterprise_upload.preview", "user": "U1", "tenant": "T-pty-pilot-01", "auth_mode": "dev-fallback", "tenant_override": { "enabled": false } },
      "expected": { "enabled": false, "source": "tenant_override", "warnings_set": ["dev_mode"], "verified": false }
    },
    {
      "id": "PT-03",
      "coverage": ["auth:decode-only", "scope:user_override", "sensitive:non_sensitive"],
      "input": { "flag": "ff.enterprise_upload.preview", "user": "U-promo", "tenant": "T-pty-pilot-01", "auth_mode": "decode-only", "user_override": { "enabled": true }, "tenant_override": { "enabled": false } },
      "expected": { "enabled": true, "source": "user_override", "reason": "user_override_precedence", "warnings_set": ["auth_not_verified"], "verified": false }
    },
    {
      "id": "PT-04",
      "coverage": ["auth:verified", "scope:tenant_override", "sensitive:sensitive_valid_approval", "ttl:valid"],
      "input": { "flag": "ff.sensitive_preview", "user": "U-sensitive", "tenant": "T-pty-pilot-01", "auth_mode": "verified", "tenant_override": { "enabled": true, "approval_ref": "APP-100001-abcd" }, "approval_ttl_state": "valid" },
      "expected": { "enabled": true, "source": "tenant_override", "warnings_set": [], "verified": true, "meta": { "approval_ref": "APP-100001-abcd", "ttl_state": "valid" } }
    },
    {
      "id": "PT-05",
      "coverage": ["auth:verified", "sensitive:sensitive_expired_approval", "ttl:expired"],
      "input": { "flag": "ff.sensitive_preview", "user": "U-sensitive", "tenant": "T-pty-pilot-01", "auth_mode": "verified", "tenant_override": { "enabled": true, "approval_ref": "APP-100004-expired" }, "approval_ttl_state": "expired" },
      "expected": { "enabled": false, "reason": "approval_expired", "meta": { "ttl_state": "expired" } }
    },
    {
      "id": "PT-06",
      "coverage": ["auth:verified", "sensitive:sensitive_missing_approval"],
      "input": { "flag": "ff.sensitive_preview", "user": "U-sensitive", "tenant": "T-pty-pilot-01", "auth_mode": "verified", "tenant_override": { "enabled": true, "approval_ref": null } },
      "expected": { "enabled": false, "reason": "requires_approval" }
    },
    {
      "id": "PT-07",
      "coverage": ["auth:decode-only", "sensitive:sensitive_auth_unverified"],
      "input": { "flag": "ff.sensitive_preview", "user": "U-sensitive", "tenant": "T-pty-pilot-01", "auth_mode": "decode-only", "tenant_override": { "enabled": true, "approval_ref": "APP-100001-abcd" } },
      "expected": { "enabled": false, "reason": "auth_not_verified", "warnings_set": ["auth_not_verified"] }
    },
    {
      "id": "PT-08",
      "coverage": ["auth:verified", "scope:default", "sensitive:non_sensitive", "stress:large_tenant_count"],
      "input": { "flag": "ff.wizard.interactive_draft", "user": "U1", "tenant": "T-pty-pilot-01", "auth_mode": "verified", "_meta": { "stress": true, "concurrent_requests": 50 } },
      "expected": { "enabled": true, "source": "default", "p99_latency_ms": "< 100 on both paths" }
    },
    {
      "id": "PT-09",
      "coverage": ["ttl:near-expiry"],
      "input": { "flag": "ff.sensitive_preview", "user": "U-sensitive", "tenant": "T-pty-pilot-01", "auth_mode": "verified", "tenant_override": { "enabled": true, "approval_ref": "APP-100007-near" }, "approval_ttl_state": "near-expiry" },
      "expected": { "enabled": true, "warnings_set": ["approval_near_expiry"], "meta": { "ttl_state": "near-expiry" } }
    },
    {
      "id": "PT-10",
      "coverage": ["ttl:stale"],
      "input": { "flag": "ff.sensitive_preview", "user": "U-sensitive", "tenant": "T-pty-pilot-01", "auth_mode": "verified", "tenant_override": { "enabled": true, "approval_ref": "APP-100006-stale" }, "approval_ttl_state": "stale" },
      "expected": { "enabled": false, "reason": "approval_expired", "meta": { "ttl_state": "stale", "operator_alert": true } }
    },
    {
      "id": "PT-11",
      "coverage": ["ttl:not-applicable", "approval_withdrawn"],
      "input": { "flag": "ff.sensitive_preview", "user": "U-sensitive", "tenant": "T-pty-pilot-01", "auth_mode": "verified", "tenant_override": { "enabled": true, "approval_ref": "APP-100005-withdrawn" } },
      "expected": { "enabled": false, "reason": "approval_withdrawn", "meta": { "ttl_state": "not-applicable" } }
    },
    {
      "id": "PT-12",
      "coverage": ["ttl:unknown", "approval_not_found"],
      "input": { "flag": "ff.sensitive_preview", "user": "U-sensitive", "tenant": "T-pty-pilot-01", "auth_mode": "verified", "tenant_override": { "enabled": true, "approval_ref": "APP-NONEXISTENT" } },
      "expected": { "enabled": false, "reason": "approval_not_found", "meta": { "ttl_state": "unknown" } }
    },
    {
      "id": "PT-13",
      "coverage": ["dual_override_precedence"],
      "input": { "flag": "ff.enterprise_upload.preview", "user": "U-promo", "tenant": "T-pty-pilot-01", "auth_mode": "verified", "user_override": { "enabled": true }, "tenant_override": { "enabled": false } },
      "expected": { "enabled": true, "source": "user_override", "reason": "user_override_precedence", "reason_chain_has": ["user_override", "tenant_override", "default"] }
    },
    {
      "id": "PT-14",
      "coverage": ["expiry_passive_read_time"],
      "input": { "flag": "ff.enterprise_upload.preview", "user": "U-old", "tenant": "T-pty-pilot-01", "auth_mode": "verified", "user_override": { "enabled": true, "expires_at": "2026-04-01T00:00:00Z" } },
      "expected": { "enabled": false, "source": "default", "warnings_set": ["user_override_expired"] }
    },
    {
      "id": "PT-15",
      "coverage": ["registry_reload_parity"],
      "input": { "flag": "ff.new_flag_added", "user": null, "tenant": null, "auth_mode": "anonymous", "_meta": { "registry_state": "freshly_reloaded" } },
      "expected": { "enabled": true, "source": "default", "registry_load_agreement": "both paths must see the same flag_registry content after reload" }
    },
    {
      "id": "PT-16",
      "coverage": ["cache_invalidation_on_write"],
      "input": { "flag": "ff.wizard.interactive_draft", "user": "U2", "tenant": "T-pty-pilot-01", "_meta": { "operation_sequence": ["write tenant_override", "immediate read"] } },
      "expected": { "read_observes_write": true, "within_seconds": 2, "note": "On db-backed with Redis, cache must invalidate before the follow-up read" }
    },
    {
      "id": "PT-17",
      "coverage": ["rollback_safety"],
      "input": { "flag": "ff.wizard.interactive_draft", "user": "U1", "tenant": "T-pty-pilot-01", "_meta": { "rollback": true, "flip_backing_mid_request": true } },
      "expected": { "enabled": "same as baseline", "note": "Flipping FF_BACKING=file mid-traffic must not corrupt a response · last-completed request wins" }
    }
  ],
  "vector_count_by_coverage_goal": {
    "auth_modes": { "verified": 6, "decode-only": 3, "dev-fallback": 1, "anonymous": 1 },
    "override_scopes": { "user_override": 3, "tenant_override": 6, "default": 4 },
    "sensitive_paths": { "non_sensitive": 4, "sensitive_valid_approval": 2, "sensitive_expired_approval": 2, "sensitive_missing_approval": 1, "sensitive_auth_unverified": 1 },
    "ttl_states": { "valid": 2, "near-expiry": 1, "expired": 1, "stale": 1, "not-applicable": 1, "unknown": 1 }
  },
  "harness_pass_criteria": {
    "file_vs_db_MUST_MATCH": "all vectors · all MUST_MATCH fields from cutover_parity_matrix.json",
    "blocking_on_any_divergence": true,
    "allowed_exceptions": ["meta.backing_state", "meta.evaluated_at (within 5s)", "meta.cache (may_differ)"]
  },
  "pair_with": {
    "cutover_parity_matrix": "docs/runtime/feature-flags-service/cutover_parity_matrix.json",
    "cutover_readiness_checklist": "docs/runtime/feature-flags-service/cutover_readiness_checklist.json",
    "verification_mode_matrix": "docs/runtime/feature-flags-service/verification_mode_matrix.json",
    "jwt_claim_examples": "docs/runtime/feature-flags-service/jwt_claim_examples.json",
    "admin_approval_store_examples": "docs/runtime/admin-control-plane-service/approval_store_examples.json"
  }
}