{
  "schema_version": "1.0",
  "baseline": "A-runtime-phase-2a",
  "phase": "Phase 2a",
  "updated_at": "2026-04-18",
  "owner": "session_a",
  "honest_note": "Canonical examples derived by running evaluator.js against the real registry.json snapshot as of 2026-04-18. When registry changes (flip · new flag · approval granted), expected values may change — re-run evaluator to regenerate. Hypothetical-registry cases use inline synthetic flags for path coverage.",
  "source_of_truth_registry": "docs/runtime/feature-flags/registry.json",
  "contract_refs": [
    "docs/runtime/feature-flags/evaluator_contract.json",
    "docs/runtime/feature-flags/evaluation_model.json"
  ],

  "groups": {
    "real_registry": "Requests evaluated against the real registry.json. Expected values reflect current (all-draft) state. Useful for regression checks.",
    "synthetic_paths": "Requests against inline hypothetical registries to cover every step of the evaluator that real draft-stage flags cannot yet exercise (internal · pilot · staged · full · paused · rolled_back · overrides)."
  },

  "real_registry_examples": [
    {
      "id": "ex-01-bootstrap-internal",
      "name": "flags.registry_v1 · stage=internal · anonymous → false (tier gate)",
      "group": "real_registry",
      "request": { "flag_key": "flags.registry_v1", "user_id": "U-anon-1", "env": "prod", "tier": "anonymous" },
      "expected": { "value": false, "source": "stage-internal", "bucket": null },
      "illustrates": "Step 8 rollout_stage_map · internal requires staff/admin tier"
    },
    {
      "id": "ex-02-bootstrap-staff",
      "name": "flags.registry_v1 · stage=internal · staff → true",
      "group": "real_registry",
      "request": { "flag_key": "flags.registry_v1", "user_id": "U-staff-1", "env": "prod", "tier": "staff" },
      "expected": { "value": true, "source": "stage-internal", "bucket": null },
      "illustrates": "Step 8 · staff tier satisfies internal stage"
    },
    {
      "id": "ex-03-dashboard-deps-fail",
      "name": "dashboard.runtime_v1 · draft · deps unsatisfied",
      "group": "real_registry",
      "request": { "flag_key": "dashboard.runtime_v1", "tenant_id": "pty-zeroth", "user_id": "U-001", "env": "prod", "tier": "staff" },
      "expected": { "value": false, "source": "dep_unsatisfied", "bucket": null },
      "illustrates": "Step 3 dependency_check · signal_pipeline.producers_v1 is draft · returns default"
    },
    {
      "id": "ex-04-cases-deps-fail",
      "name": "cases.runtime_v1 · draft · deps unsatisfied",
      "group": "real_registry",
      "request": { "flag_key": "cases.runtime_v1", "tenant_id": "pty-zeroth", "user_id": "U-002", "env": "prod", "tier": "admin" },
      "expected": { "value": false, "source": "dep_unsatisfied", "bucket": null },
      "illustrates": "Step 3 · deps on signal_pipeline + admin.control_plane · cascade block"
    },
    {
      "id": "ex-05-unknown-flag",
      "name": "unknown_flag returns false · source=unknown_flag",
      "group": "real_registry",
      "request": { "flag_key": "nonexistent.flag_v1", "user_id": "U-003", "env": "prod", "tier": "member" },
      "expected": { "value": false, "source": "unknown_flag", "bucket": null },
      "illustrates": "Step 1 flag_exists_check · alertable metric (flag_eval_unknown)"
    },
    {
      "id": "ex-06-marketplace-deps-fail",
      "name": "platform.marketplace_listing_enabled · deps unsatisfied (tenant.runtime_v1)",
      "group": "real_registry",
      "request": { "flag_key": "platform.marketplace_listing_enabled", "user_id": "U-004", "env": "prod", "tier": "admin" },
      "expected": { "value": false, "source": "dep_unsatisfied", "bucket": null },
      "illustrates": "Step 3 · sensitive flag dependency chain"
    },
    {
      "id": "ex-07-wizard-deps-fail",
      "name": "wizard.runtime_v1 · deps unsatisfied (admin.control_plane_v1)",
      "group": "real_registry",
      "request": { "flag_key": "wizard.runtime_v1", "user_id": "U-005", "env": "prod", "tier": "platinum" },
      "expected": { "value": false, "source": "dep_unsatisfied", "bucket": null },
      "illustrates": "Step 3 · wizard requires admin control plane"
    },
    {
      "id": "ex-08-generate-deps-fail",
      "name": "generate.runtime_v1 · deps unsatisfied",
      "group": "real_registry",
      "request": { "flag_key": "generate.runtime_v1", "user_id": "U-006", "env": "prod", "tier": "staff" },
      "expected": { "value": false, "source": "dep_unsatisfied", "bucket": null },
      "illustrates": "Step 3"
    },
    {
      "id": "ex-09-tenant-deps-fail",
      "name": "tenant.runtime_v1 · sensitive · deps unsatisfied",
      "group": "real_registry",
      "request": { "flag_key": "tenant.runtime_v1", "user_id": "U-007", "env": "prod", "tier": "admin" },
      "expected": { "value": false, "source": "dep_unsatisfied", "bucket": null },
      "illustrates": "Step 3 · sensitive + deps"
    },
    {
      "id": "ex-10-admin-approval-missing",
      "name": "admin.control_plane_v1 · draft · sensitive · approval_ref=null → approval_missing",
      "group": "real_registry",
      "request": { "flag_key": "admin.control_plane_v1", "user_id": "U-008", "env": "prod", "tier": "admin" },
      "expected": { "value": false, "source": "approval_missing", "bucket": null },
      "illustrates": "Step 4 approval_gate · requires_approval=true + last_approval_ref=null → default"
    },
    {
      "id": "ex-11-tenant-template-deps",
      "name": "tenant template flag · deps unsatisfied",
      "group": "real_registry",
      "request": { "flag_key": "tenant.<tenant_id>.wizard_enabled", "user_id": "U-009", "env": "prod", "tier": "admin" },
      "expected": { "value": false, "source": "dep_unsatisfied", "bucket": null },
      "illustrates": "Step 3 · template key · same evaluation semantics"
    }
  ],

  "synthetic_registry": {
    "description_en": "Inline minimal registry used ONLY by synthetic examples below. Not loaded into production evaluator.",
    "flags": [
      {
        "id": "syn-full", "key": "syn.full_on",
        "description_th": "synthetic · full rollout", "description_en": "synthetic · full rollout",
        "owner_module": "flags", "default_value": false, "type": "boolean",
        "allowed_scopes": ["global"], "rollout_stage": "full",
        "requires_approval": false, "sensitive_flag": false,
        "approval_matrix_row": null, "dependencies": [],
        "audit": { "created_at": "2026-04-18", "created_by": "synthetic", "last_flipped_at": "2026-04-18", "last_approval_ref": null, "last_flipped_by": "synthetic" },
        "planning_ref": "docs/planning/feature-flags.html", "contract_ref": null,
        "binding_status": "mock", "honest_note": "Synthetic · for example coverage only"
      },
      {
        "id": "syn-paused", "key": "syn.paused_ignores_overrides",
        "description_th": "synthetic · paused", "description_en": "synthetic · paused",
        "owner_module": "flags", "default_value": false, "type": "boolean",
        "allowed_scopes": ["global", "tenant"], "rollout_stage": "paused",
        "requires_approval": false, "sensitive_flag": false,
        "approval_matrix_row": null, "dependencies": [],
        "audit": { "created_at": "2026-04-18", "created_by": "synthetic" },
        "planning_ref": "", "contract_ref": null, "binding_status": "mock",
        "honest_note": "Synthetic · paused · overrides should NOT win"
      },
      {
        "id": "syn-rollback", "key": "syn.rolled_back",
        "description_th": "synthetic · rolled_back", "description_en": "synthetic · rolled_back",
        "owner_module": "flags", "default_value": false, "type": "boolean",
        "allowed_scopes": ["global"], "rollout_stage": "rolled_back",
        "requires_approval": false, "sensitive_flag": false,
        "approval_matrix_row": null, "dependencies": [],
        "audit": { "created_at": "2026-04-18", "created_by": "synthetic" },
        "planning_ref": "", "contract_ref": null, "binding_status": "mock",
        "honest_note": "Synthetic · rolled_back · treated as off forever"
      },
      {
        "id": "syn-staged", "key": "syn.staged_25",
        "description_th": "synthetic · staged 25pct", "description_en": "synthetic · staged 25pct",
        "owner_module": "flags", "default_value": false, "type": "boolean",
        "allowed_scopes": ["global"], "rollout_stage": "staged", "rollout_pct": 25,
        "requires_approval": false, "sensitive_flag": false,
        "approval_matrix_row": null, "dependencies": [],
        "audit": { "created_at": "2026-04-18", "created_by": "synthetic" },
        "planning_ref": "", "contract_ref": null, "binding_status": "mock",
        "honest_note": "Synthetic · staged at 25%"
      },
      {
        "id": "syn-override-target", "key": "syn.override_target",
        "description_th": "synthetic · default off · user/tenant override possible",
        "description_en": "synthetic · default off · user/tenant override possible",
        "owner_module": "flags", "default_value": false, "type": "boolean",
        "allowed_scopes": ["global","tenant","user"], "rollout_stage": "draft",
        "requires_approval": false, "sensitive_flag": false,
        "approval_matrix_row": null, "dependencies": [],
        "audit": { "created_at": "2026-04-18", "created_by": "synthetic", "last_approval_ref": "APP-synthetic-001" },
        "planning_ref": "", "contract_ref": null, "binding_status": "mock",
        "honest_note": "Synthetic · used for override precedence tests"
      }
    ]
  },

  "synthetic_examples": [
    {
      "id": "syn-ex-01-full",
      "name": "stage=full → true for everyone",
      "group": "synthetic_paths",
      "use_registry": "synthetic_registry",
      "request": { "flag_key": "syn.full_on", "user_id": "U-1", "env": "prod", "tier": "anonymous" },
      "expected": { "value": true, "source": "stage-full", "bucket": null },
      "illustrates": "Step 8 · full stage returns true regardless of tier"
    },
    {
      "id": "syn-ex-02-paused-short",
      "name": "stage=paused short-circuits · overrides ignored",
      "group": "synthetic_paths",
      "use_registry": "synthetic_registry",
      "request": {
        "flag_key": "syn.paused_ignores_overrides", "user_id": "U-2", "env": "prod", "tier": "admin",
        "overrides": { "user": { "syn.paused_ignores_overrides": true }, "tenant": { "syn.paused_ignores_overrides": true } }
      },
      "expected": { "value": false, "source": "paused", "bucket": null },
      "illustrates": "Step 2 · paused short-circuits · overrides cannot bypass safety circuit"
    },
    {
      "id": "syn-ex-03-rolled-back",
      "name": "stage=rolled_back returns default",
      "group": "synthetic_paths",
      "use_registry": "synthetic_registry",
      "request": { "flag_key": "syn.rolled_back", "user_id": "U-3", "env": "prod", "tier": "admin" },
      "expected": { "value": false, "source": "rolled_back", "bucket": null },
      "illustrates": "Step 2 · rolled_back = permanently off until re-promoted"
    },
    {
      "id": "syn-ex-04-user-override",
      "name": "user override beats default",
      "group": "synthetic_paths",
      "use_registry": "synthetic_registry",
      "request": {
        "flag_key": "syn.override_target", "user_id": "U-4", "env": "prod", "tier": "member",
        "overrides": { "user": { "syn.override_target": true } }
      },
      "expected": { "value": true, "source": "user_override", "bucket": null },
      "illustrates": "Step 5 · user override wins over stage-draft default"
    },
    {
      "id": "syn-ex-05-tenant-override",
      "name": "tenant override beats default (no user override present)",
      "group": "synthetic_paths",
      "use_registry": "synthetic_registry",
      "request": {
        "flag_key": "syn.override_target", "user_id": "U-5", "env": "prod", "tier": "member",
        "overrides": { "tenant": { "syn.override_target": true } }
      },
      "expected": { "value": true, "source": "tenant_override", "bucket": null },
      "illustrates": "Step 6 · tenant override wins when no user override"
    },
    {
      "id": "syn-ex-06-user-beats-tenant",
      "name": "user override wins over tenant override",
      "group": "synthetic_paths",
      "use_registry": "synthetic_registry",
      "request": {
        "flag_key": "syn.override_target", "user_id": "U-6", "env": "prod", "tier": "member",
        "overrides": { "user": { "syn.override_target": false }, "tenant": { "syn.override_target": true } }
      },
      "expected": { "value": false, "source": "user_override", "bucket": null },
      "illustrates": "Precedence rule pr-2 · user > tenant"
    },
    {
      "id": "syn-ex-07-staged-bucket-low",
      "name": "staged 25% · user-with-low-bucket → true",
      "group": "synthetic_paths",
      "use_registry": "synthetic_registry",
      "request": { "flag_key": "syn.staged_25", "user_id": "bucket-low-1", "env": "prod", "tier": "member" },
      "expected": { "value": null, "source": "rollout_pct", "bucket": null, "note": "bucket is deterministic from hash · run evaluator.hashBucket('bucket-low-1|syn.staged_25') to verify" },
      "illustrates": "Step 7 · deterministic bucketing · hashed value mod 100 < 25 → true"
    },
    {
      "id": "syn-ex-08-determinism",
      "name": "same request twice → same value, source, bucket",
      "group": "synthetic_paths",
      "use_registry": "synthetic_registry",
      "request": { "flag_key": "syn.staged_25", "user_id": "U-determ", "env": "prod", "tier": "member" },
      "expected": { "value": null, "source": "rollout_pct", "note": "evaluator.verifyDeterminism must return ok:true" },
      "illustrates": "Determinism guarantee · pr in contract"
    }
  ],

  "runner_notes": {
    "how_to_run_node": "cd docs/runtime/feature-flags && node -e \"const FF=require('./evaluator.js');const reg=require('./registry.json');const ex=require('./evaluator_examples.json');for(const e of ex.real_registry_examples){const r=FF.checkExample(reg,e);console.log((r.pass?'✅':'❌')+' '+e.name);}\"",
    "how_to_run_browser": "Open evaluator.html → Examples tab → click 'Run all' button",
    "pass_criteria": "got.value === expected.value AND got.source === expected.source AND (expected.bucket == null OR got.bucket === expected.bucket)",
    "coverage": "Real examples cover 7 of 9 evaluator steps via draft-state registry (all flags gated by deps or approval). Synthetic examples cover steps 2 (paused · rolled_back) · 5 · 6 · 7 · 8-full."
  }
}