Add BitGate distribution, API, policy, and explainability roadmap

docs/TODO.md

@@ -0,0 +1,178 @@
+# BitGate — open items
+
+Updated: 2026-08-10
+
+BitGate is the standalone governance and policy engine in this repository. The
+existing `@bitgate/core`, `@bitgate/nostr`, `@bitgate/runtime`, `@bitgate/verify`,
+`@bitgate/testing`, `@bitgate/widget`, and compatibility packages are existing
+surfaces. The distribution and API work below must be additive and must not
+break current BitGate consumers or the behavior characterized from BitVid and
+BitRoad.
+
+## Priority 1 — Distribution
+
+- [ ] Guarantee one browser-ready standalone build: `bitgate.js`.
+    - [ ] Require no npm at runtime.
+    - [ ] Require no runtime dependencies.
+    - [ ] Work directly from vanilla HTML.
+- [ ] Publish predictable downloadable release artifacts.
+- [ ] Provide both an ES module and an npm package.
+- [ ] Verify the standalone build works from ordinary static HTTPS hosts and
+      localhost development without requiring a framework or bundler.
+- [ ] Document `file://` limitations and the recommended local development
+      server path.
+
+## Priority 2 — Canonical API
+
+- [ ] Establish one obvious entry point, for example:
+
+      const decision = await gate.evaluate({
+        viewer,
+        item,
+        action: "view"
+      });
+
+- [ ] Standardize decision output:
+
+      {
+        visibility,
+        ranking,
+        interaction,
+        transaction,
+        reasons,
+        evidence
+      }
+
+- [ ] Keep the four decision axes independent:
+    - [ ] visibility
+    - [ ] ranking
+    - [ ] interaction
+    - [ ] transaction
+- [ ] Do not collapse all policy outcomes into `allowed`/`blocked`.
+- [ ] Define stable machine-readable reason codes, for example:
+    - [ ] `USER_MUTED`
+    - [ ] `FOLLOWED_USER_REPORTED`
+    - [ ] `MALWARE_SIGNAL`
+    - [ ] `SPAM_SIGNAL`
+    - [ ] `POLICY_BLOCK`
+- [ ] Define how any legacy adapter verdicts map onto the canonical four-axis
+      decision without losing information.
+- [ ] Define deterministic behavior when an axis is not applicable to an
+      action, such as transaction policy for a read-only view.
+
+## Priority 3 — Shared Context
+
+- [ ] Accept a standardized viewer context:
+
+      {
+        pubkey,
+        follows,
+        mutes,
+        relays,
+        trustGraph,
+        interests
+      }
+
+- [ ] Avoid requiring BitGate-specific conversions when data already comes
+      from BitLogin or Nostr.
+- [ ] Define optional versus required context fields and safe defaults for
+      missing, stale, or unavailable context.
+- [ ] Keep context normalization separate from policy evaluation so applications
+      can pass through native BitLogin/Nostr structures without needless copying.
+- [ ] Define privacy boundaries for context: do not require raw viewer identity,
+      cross-site tracking data, or unnecessary behavioral history.
+
+## Priority 4 — Policies
+
+- [ ] Formalize the `bitgate/1` policy schema.
+- [ ] Make policies serializable, hashable, signable, publishable, and forkable.
+- [ ] Allow policies to be loaded from signed Nostr events.
+- [ ] Verify policy signatures, schema versions, hashes, and issuer metadata
+      before using a policy; fail safely when verification is ambiguous.
+- [ ] Support named policy profiles, for example:
+    - [ ] `social`
+    - [ ] `comments`
+    - [ ] `marketplace-browse`
+    - [ ] `marketplace-checkout`
+    - [ ] `messaging`
+- [ ] Keep app-specific policy configuration outside the core engine.
+- [ ] Define policy precedence, composition, conflict resolution, and explicit
+      override rules when multiple policies apply.
+- [ ] Make policy evaluation deterministic and testable for the same input,
+      policy set, and evaluation time.
+- [ ] Document policy expiry, revocation, cache behavior, and offline behavior.
+
+## Priority 5 — Explainability
+
+- [ ] Make every decision explainable.
+- [ ] Return machine-readable reasons.
+- [ ] Return optional human-readable explanations without making UI copy part
+      of the stable machine contract.
+- [ ] Support `gate.explain(decision)`.
+- [ ] Make it straightforward for applications to answer:
+    - [ ] “Why was this hidden?”
+    - [ ] “Why can't I reply?”
+    - [ ] “Why is checkout disabled?”
+- [ ] Include enough evidence references to audit a decision without exposing
+      unnecessary private viewer data.
+- [ ] Distinguish the policy reason, the evidence source, and the resulting
+      action; do not imply that a signal is proof when it is only a heuristic.
+- [ ] Define stable explanation behavior for conflicting signals, unavailable
+      evidence, expired policies, and fail-open/fail-closed choices.
+
+## Priority 6 — Documentation
+
+- [ ] Add a vanilla HTML example.
+- [ ] Add a BitLogin + BitGate example.
+- [ ] Add a social feed example.
+- [ ] Add a commerce example.
+- [ ] Document the difference between:
+    - [ ] hide
+    - [ ] downrank
+    - [ ] warn
+    - [ ] interaction deny
+    - [ ] transaction deny
+- [ ] Document the canonical API in relation to the existing package APIs and
+      how current consumers migrate without a forced rewrite.
+- [ ] Document the security and privacy boundaries of local policy evaluation,
+      signed Nostr policies, and remotely supplied evidence.
+
+## Compatibility and testing gates
+
+- [ ] Preserve existing package APIs while introducing the canonical BitGate
+      API.
+- [ ] Preserve the behavior characterized from BitVid and BitRoad during
+      extraction and future policy-engine changes.
+- [ ] Add unit tests for canonical decision-axis independence, stable reason
+      codes, legacy verdict mapping, policy precedence, and explainability.
+- [ ] Add tests for signed policy verification, malformed policies, unknown
+      schema versions, expired policies, and ambiguous evidence.
+- [ ] Add browser integration tests for the standalone `bitgate.js` artifact
+      from vanilla HTML.
+- [ ] Test the npm package and ES-module import paths from a clean consumer
+      project.
+- [ ] Test the definition-of-done examples against the published artifact.
+- [ ] Run the existing build, typecheck, and test suite before and after
+      changes; standalone work must not replace or mutate current package
+      output.
+
+## Definition of done
+
+A developer can drop `bitgate.js` into a page, pass it a viewer, item, and
+action, and receive a consistent, explainable policy decision without needing
+to understand BitGate internals. The same canonical engine is available as an
+ES module and npm package, while existing BitGate consumers continue to work
+unchanged.
+
+## Open design decisions
+
+- [ ] Choose the exact `bitgate/1` event kind and signed-policy event format.
+- [ ] Choose the canonical TypeScript types and runtime validation strategy.
+- [ ] Decide whether `gate.explain(decision)` is pure/local only or may resolve
+      additional evidence asynchronously.
+- [ ] Decide default fail-open/fail-closed behavior per axis and per action.
+- [ ] Decide how policy profile discovery works without creating a centralized
+      authority or leaking private application context.
+- [ ] Decide whether standalone output is generated from the canonical engine
+      directly or from a separately maintained browser entry point.
+- [ ] Decide how browser builds expose version and integrity metadata.