@almadar/std 16.143.0 → 16.145.0

package/behaviors/registry/ml/atoms/std-ml-posterior.orb

@@ -0,0 +1,669 @@
+{
+  "description": "std-ml-posterior — the statistical rung (R2) of the intelligence ladder. Holds a Beta(alpha, beta) belief over an unknown success rate and updates it from boolean observations (Bayesian updating, knowledge tracing, Thompson-sampling prior). After each observation it draws samples from the posterior, computes a credible interval, and decides: MASTERY_REACHED when the mean clears the floor with a tight interval, REMEDIATION_NEEDED when the mean sits at or below the ceiling with the same confidence, or EVIDENCE_INSUFFICIENT — the abstain — when the interval is still too wide to trust. Use when a hand-tuned score needs to become a belief that can say 'not enough evidence yet' (mastery, skill, risk, preference, difficulty).",
+  "ledger": {
+    "entries": {
+      "ent_01KYBM8SPD24VMR9HBQY0RM82A": {
+        "bakedName": "Posterior",
+        "curName": "Posterior",
+        "id": "ent_01KYBM8SPD24VMR9HBQY0RM82A",
+        "kind": "entity",
+        "owner": "workspace",
+        "renames": []
+      },
+      "evt_01KYBM8SPDEVSWTYZ4MWW9NPR1": {
+        "bakedName": "INIT",
+        "curName": "INIT",
+        "id": "evt_01KYBM8SPDEVSWTYZ4MWW9NPR1",
+        "kind": "event",
+        "owner": "workspace",
+        "parent": "trt_01KYBM8SPDR0V9Y61Y00APN1PT",
+        "renames": []
+      },
+      "evt_01KYBM8SPDPGKNPVWPME4HZA7C": {
+        "bakedName": "MASTERY_REACHED",
+        "curName": "MASTERY_REACHED",
+        "id": "evt_01KYBM8SPDPGKNPVWPME4HZA7C",
+        "kind": "event",
+        "owner": "workspace",
+        "parent": "trt_01KYBM8SPDR0V9Y61Y00APN1PT",
+        "renames": []
+      },
+      "evt_01KYBM8SPDSVKBPWV2V0GTMS44": {
+        "bakedName": "EVIDENCE_INSUFFICIENT",
+        "curName": "EVIDENCE_INSUFFICIENT",
+        "id": "evt_01KYBM8SPDSVKBPWV2V0GTMS44",
+        "kind": "event",
+        "owner": "workspace",
+        "parent": "trt_01KYBM8SPDR0V9Y61Y00APN1PT",
+        "renames": []
+      },
+      "evt_01KYBM8SPDW5ZGB5SDCQD74JSB": {
+        "bakedName": "REMEDIATION_NEEDED",
+        "curName": "REMEDIATION_NEEDED",
+        "id": "evt_01KYBM8SPDW5ZGB5SDCQD74JSB",
+        "kind": "event",
+        "owner": "workspace",
+        "parent": "trt_01KYBM8SPDR0V9Y61Y00APN1PT",
+        "renames": []
+      },
+      "evt_01KYBM8SPDZNET4JJKM8MJ8TYE": {
+        "bakedName": "OBSERVE",
+        "curName": "OBSERVE",
+        "id": "evt_01KYBM8SPDZNET4JJKM8MJ8TYE",
+        "kind": "event",
+        "owner": "workspace",
+        "parent": "trt_01KYBM8SPDR0V9Y61Y00APN1PT",
+        "renames": []
+      },
+      "orb_01KYBM8SPCWYRYTP9GG343Z4JN": {
+        "bakedName": "MlPosteriorOrbital",
+        "curName": "MlPosteriorOrbital",
+        "id": "orb_01KYBM8SPCWYRYTP9GG343Z4JN",
+        "kind": "orbital",
+        "owner": "workspace",
+        "renames": []
+      },
+      "pag_01KYBM8SPEWW6AQ9C7AXCKFTJM": {
+        "bakedName": "MlPosteriorPage",
+        "curName": "MlPosteriorPage",
+        "id": "pag_01KYBM8SPEWW6AQ9C7AXCKFTJM",
+        "kind": "page",
+        "owner": "workspace",
+        "renames": []
+      },
+      "trt_01KYBM8SPDR0V9Y61Y00APN1PT": {
+        "bakedName": "PosteriorBelief",
+        "curName": "PosteriorBelief",
+        "id": "trt_01KYBM8SPDR0V9Y61Y00APN1PT",
+        "kind": "trait",
+        "owner": "workspace",
+        "renames": []
+      }
+    },
+    "schemaVersion": 1
+  },
+  "name": "std-ml-posterior",
+  "orbitals": [
+    {
+      "entity": {
+        "fields": [
+          {
+            "default": 1.0,
+            "description": "Beta distribution success count (prior + observed successes).",
+            "name": "alpha",
+            "type": "number"
+          },
+          {
+            "default": 1.0,
+            "description": "Beta distribution failure count (prior + observed failures).",
+            "name": "beta",
+            "type": "number"
+          },
+          {
+            "default": 0.0,
+            "description": "Posterior mean: alpha / (alpha + beta).",
+            "name": "mean",
+            "type": "number"
+          },
+          {
+            "default": 0.0,
+            "description": "Lower bound of the last computed credible interval.",
+            "name": "intervalLow",
+            "type": "number"
+          },
+          {
+            "default": 0.0,
+            "description": "Upper bound of the last computed credible interval.",
+            "name": "intervalHigh",
+            "type": "number"
+          },
+          {
+            "default": 0.0,
+            "description": "Number of observations folded into the posterior so far.",
+            "name": "observations",
+            "type": "number"
+          },
+          {
+            "default": "idle",
+            "name": "status",
+            "type": "string",
+            "values": [
+              "idle",
+              "insufficient",
+              "mastered",
+              "remediate"
+            ]
+          }
+        ],
+        "id": "ent_01KYBM8SPD24VMR9HBQY0RM82A",
+        "name": "Posterior",
+        "persistence": "runtime"
+      },
+      "id": "orb_01KYBM8SPCWYRYTP9GG343Z4JN",
+      "name": "MlPosteriorOrbital",
+      "pages": [
+        {
+          "id": "pag_01KYBM8SPEWW6AQ9C7AXCKFTJM",
+          "name": "MlPosteriorPage",
+          "path": "/ml-posterior",
+          "traits": [
+            {
+              "ref": "PosteriorBelief",
+              "refId": "trt_01KYBM8SPDR0V9Y61Y00APN1PT"
+            }
+          ]
+        }
+      ],
+      "traits": [
+        {
+          "category": "lifecycle",
+          "config": {
+            "intervalWidthMax": {
+              "default": 0.3,
+              "description": "Above this width the posterior is too uncertain to decide — abstain with EVIDENCE_INSUFFICIENT.",
+              "label": "Max credible-interval width",
+              "tier": "policy",
+              "type": "float"
+            },
+            "masteryFloor": {
+              "default": 0.8,
+              "description": "Posterior mean at or above this, with a tight interval, licenses MASTERY_REACHED.",
+              "label": "Mastery floor",
+              "tier": "policy",
+              "type": "float"
+            },
+            "priorAlpha": {
+              "default": 1.0,
+              "description": "Beta prior success pseudo-count before any observation.",
+              "label": "Prior alpha",
+              "tier": "domain",
+              "type": "float"
+            },
+            "priorBeta": {
+              "default": 1.0,
+              "description": "Beta prior failure pseudo-count before any observation.",
+              "label": "Prior beta",
+              "tier": "domain",
+              "type": "float"
+            },
+            "remediationCeiling": {
+              "default": 0.4,
+              "description": "Posterior mean at or below this, with a tight interval, licenses REMEDIATION_NEEDED.",
+              "label": "Remediation ceiling",
+              "tier": "policy",
+              "type": "float"
+            },
+            "sampleCount": {
+              "default": 200.0,
+              "description": "Number of Monte Carlo draws from the Beta posterior used to estimate the credible interval.",
+              "label": "Posterior sample count",
+              "tier": "infra",
+              "type": "int"
+            }
+          },
+          "emits": [
+            {
+              "description": "The posterior mean clears masteryFloor with a credible interval narrow enough to trust.",
+              "event": "MASTERY_REACHED",
+              "eventId": "evt_01KYBM8SPDPGKNPVWPME4HZA7C",
+              "payloadSchema": [
+                {
+                  "name": "mean",
+                  "required": true,
+                  "type": "float"
+                },
+                {
+                  "name": "intervalLow",
+                  "required": true,
+                  "type": "float"
+                },
+                {
+                  "name": "intervalHigh",
+                  "required": true,
+                  "type": "float"
+                }
+              ],
+              "scope": "external",
+              "tier": "primary"
+            },
+            {
+              "description": "The posterior mean is at or below remediationCeiling with a credible interval narrow enough to trust.",
+              "event": "REMEDIATION_NEEDED",
+              "eventId": "evt_01KYBM8SPDW5ZGB5SDCQD74JSB",
+              "payloadSchema": [
+                {
+                  "name": "mean",
+                  "required": true,
+                  "type": "float"
+                },
+                {
+                  "name": "intervalLow",
+                  "required": true,
+                  "type": "float"
+                },
+                {
+                  "name": "intervalHigh",
+                  "required": true,
+                  "type": "float"
+                }
+              ],
+              "scope": "external",
+              "tier": "primary"
+            },
+            {
+              "description": "The abstain — the credible interval is still wider than intervalWidthMax, so no verdict is licensed yet.",
+              "event": "EVIDENCE_INSUFFICIENT",
+              "eventId": "evt_01KYBM8SPDSVKBPWV2V0GTMS44",
+              "payloadSchema": [
+                {
+                  "name": "mean",
+                  "required": true,
+                  "type": "float"
+                },
+                {
+                  "name": "intervalLow",
+                  "required": true,
+                  "type": "float"
+                },
+                {
+                  "name": "intervalHigh",
+                  "required": true,
+                  "type": "float"
+                }
+              ],
+              "scope": "external",
+              "tier": "primary"
+            }
+          ],
+          "entityContract": {
+            "provides": [
+              "alpha",
+              "beta",
+              "intervalHigh",
+              "intervalLow",
+              "mean",
+              "observations",
+              "status"
+            ],
+            "requires": []
+          },
+          "entityRebindable": true,
+          "entityRefIds": {
+            "Posterior": "ent_01KYBM8SPD24VMR9HBQY0RM82A"
+          },
+          "id": "trt_01KYBM8SPDR0V9Y61Y00APN1PT",
+          "linkedEntity": "Posterior",
+          "linkedEntityId": "ent_01KYBM8SPD24VMR9HBQY0RM82A",
+          "name": "PosteriorBelief",
+          "scope": "instance",
+          "stateMachine": {
+            "events": [
+              {
+                "id": "evt_01KYBM8SPDEVSWTYZ4MWW9NPR1",
+                "key": "INIT",
+                "name": "Initialize"
+              },
+              {
+                "id": "evt_01KYBM8SPDZNET4JJKM8MJ8TYE",
+                "key": "OBSERVE",
+                "name": "Observe",
+                "payloadSchema": [
+                  {
+                    "name": "outcome",
+                    "required": true,
+                    "type": "boolean"
+                  }
+                ]
+              },
+              {
+                "description": "The posterior mean clears masteryFloor with a credible interval narrow enough to trust.",
+                "id": "evt_01KYBM8SPDPGKNPVWPME4HZA7C",
+                "key": "MASTERY_REACHED",
+                "name": "Mastery Reached",
+                "payloadSchema": [
+                  {
+                    "name": "mean",
+                    "required": true,
+                    "type": "float"
+                  },
+                  {
+                    "name": "intervalLow",
+                    "required": true,
+                    "type": "float"
+                  },
+                  {
+                    "name": "intervalHigh",
+                    "required": true,
+                    "type": "float"
+                  }
+                ],
+                "tier": "primary"
+              },
+              {
+                "description": "The posterior mean is at or below remediationCeiling with a credible interval narrow enough to trust.",
+                "id": "evt_01KYBM8SPDW5ZGB5SDCQD74JSB",
+                "key": "REMEDIATION_NEEDED",
+                "name": "Remediation Needed",
+                "payloadSchema": [
+                  {
+                    "name": "mean",
+                    "required": true,
+                    "type": "float"
+                  },
+                  {
+                    "name": "intervalLow",
+                    "required": true,
+                    "type": "float"
+                  },
+                  {
+                    "name": "intervalHigh",
+                    "required": true,
+                    "type": "float"
+                  }
+                ],
+                "tier": "primary"
+              },
+              {
+                "description": "The abstain — the credible interval is still wider than intervalWidthMax, so no verdict is licensed yet.",
+                "id": "evt_01KYBM8SPDSVKBPWV2V0GTMS44",
+                "key": "EVIDENCE_INSUFFICIENT",
+                "name": "Evidence Insufficient",
+                "payloadSchema": [
+                  {
+                    "name": "mean",
+                    "required": true,
+                    "type": "float"
+                  },
+                  {
+                    "name": "intervalLow",
+                    "required": true,
+                    "type": "float"
+                  },
+                  {
+                    "name": "intervalHigh",
+                    "required": true,
+                    "type": "float"
+                  }
+                ],
+                "tier": "primary"
+              }
+            ],
+            "states": [
+              {
+                "isInitial": true,
+                "name": "idle"
+              }
+            ],
+            "transitions": [
+              {
+                "effects": [
+                  [
+                    "set",
+                    "@entity.alpha",
+                    "@config.priorAlpha"
+                  ],
+                  [
+                    "set",
+                    "@entity.beta",
+                    "@config.priorBeta"
+                  ],
+                  [
+                    "set",
+                    "@entity.mean",
+                    [
+                      "/",
+                      "@config.priorAlpha",
+                      [
+                        "+",
+                        "@config.priorAlpha",
+                        "@config.priorBeta"
+                      ]
+                    ]
+                  ],
+                  [
+                    "set",
+                    "@entity.intervalLow",
+                    0.0
+                  ],
+                  [
+                    "set",
+                    "@entity.intervalHigh",
+                    0.0
+                  ],
+                  [
+                    "set",
+                    "@entity.observations",
+                    0.0
+                  ],
+                  [
+                    "set",
+                    "@entity.status",
+                    "idle"
+                  ]
+                ],
+                "event": "INIT",
+                "eventId": "evt_01KYBM8SPDEVSWTYZ4MWW9NPR1",
+                "from": "idle",
+                "to": "idle"
+              },
+              {
+                "effects": [
+                  [
+                    "set",
+                    "@entity.alpha",
+                    [
+                      "if",
+                      "@payload.outcome",
+                      [
+                        "+",
+                        "@entity.alpha",
+                        1.0
+                      ],
+                      "@entity.alpha"
+                    ]
+                  ],
+                  [
+                    "set",
+                    "@entity.beta",
+                    [
+                      "if",
+                      "@payload.outcome",
+                      "@entity.beta",
+                      [
+                        "+",
+                        "@entity.beta",
+                        1.0
+                      ]
+                    ]
+                  ],
+                  [
+                    "set",
+                    "@entity.observations",
+                    [
+                      "+",
+                      "@entity.observations",
+                      1.0
+                    ]
+                  ],
+                  [
+                    "set",
+                    "@entity.mean",
+                    [
+                      "/",
+                      "@entity.alpha",
+                      [
+                        "+",
+                        "@entity.alpha",
+                        "@entity.beta"
+                      ]
+                    ]
+                  ],
+                  [
+                    "let",
+                    [
+                      [
+                        "samples",
+                        [
+                          "prob/sample",
+                          "@config.sampleCount",
+                          [
+                            "prob/beta",
+                            "@entity.alpha",
+                            "@entity.beta"
+                          ]
+                        ]
+                      ],
+                      [
+                        "interval",
+                        [
+                          "prob/credible-interval",
+                          "@samples",
+                          0.05
+                        ]
+                      ],
+                      [
+                        "low",
+                        [
+                          "array/nth",
+                          "@interval",
+                          0.0
+                        ]
+                      ],
+                      [
+                        "high",
+                        [
+                          "array/nth",
+                          "@interval",
+                          1.0
+                        ]
+                      ],
+                      [
+                        "width",
+                        [
+                          "-",
+                          "@high",
+                          "@low"
+                        ]
+                      ]
+                    ],
+                    [
+                      "do",
+                      [
+                        "set",
+                        "@entity.intervalLow",
+                        "@low"
+                      ],
+                      [
+                        "set",
+                        "@entity.intervalHigh",
+                        "@high"
+                      ],
+                      [
+                        "if",
+                        [
+                          ">",
+                          "@width",
+                          "@config.intervalWidthMax"
+                        ],
+                        [
+                          "do",
+                          [
+                            "set",
+                            "@entity.status",
+                            "insufficient"
+                          ],
+                          [
+                            "emit",
+                            "EVIDENCE_INSUFFICIENT",
+                            {
+                              "intervalHigh": "@high",
+                              "intervalLow": "@low",
+                              "mean": "@entity.mean"
+                            }
+                          ]
+                        ],
+                        [
+                          "if",
+                          [
+                            ">=",
+                            "@entity.mean",
+                            "@config.masteryFloor"
+                          ],
+                          [
+                            "do",
+                            [
+                              "set",
+                              "@entity.status",
+                              "mastered"
+                            ],
+                            [
+                              "emit",
+                              "MASTERY_REACHED",
+                              {
+                                "intervalHigh": "@high",
+                                "intervalLow": "@low",
+                                "mean": "@entity.mean"
+                              }
+                            ]
+                          ],
+                          [
+                            "if",
+                            [
+                              "<=",
+                              "@entity.mean",
+                              "@config.remediationCeiling"
+                            ],
+                            [
+                              "do",
+                              [
+                                "set",
+                                "@entity.status",
+                                "remediate"
+                              ],
+                              [
+                                "emit",
+                                "REMEDIATION_NEEDED",
+                                {
+                                  "intervalHigh": "@high",
+                                  "intervalLow": "@low",
+                                  "mean": "@entity.mean"
+                                }
+                              ]
+                            ],
+                            [
+                              "do",
+                              [
+                                "set",
+                                "@entity.status",
+                                "insufficient"
+                              ],
+                              [
+                                "emit",
+                                "EVIDENCE_INSUFFICIENT",
+                                {
+                                  "intervalHigh": "@high",
+                                  "intervalLow": "@low",
+                                  "mean": "@entity.mean"
+                                }
+                              ]
+                            ]
+                          ]
+                        ]
+                      ]
+                    ]
+                  ]
+                ],
+                "event": "OBSERVE",
+                "eventId": "evt_01KYBM8SPDZNET4JJKM8MJ8TYE",
+                "from": "idle",
+                "to": "idle"
+              }
+            ]
+          }
+        }
+      ]
+    }
+  ],
+  "schemaVersion": 1,
+  "version": "1.0.0"
+}