feat: adapter contract, commerce proof-of-fit, and reusability docs

Proves the engine did not stay video-specific during extraction.

- application adapter contract in core (createApplicationAdapter,
  evaluateObject, collectTargets): an object names the targets that govern it
  and the strictest verdict reaching any of them wins, so denying a seller
  takes their whole catalogue down with no cascade logic in the application
- examples/commerce: a marketplace on the public API covering all ten
  proof-of-fit behaviors the plan requires, including that no core change was
  needed. One product, one snapshot, four surfaces, four different verdicts.
- README, integration guide, per-example README, CHANGELOG, four ADRs, and
  GPL-3.0-or-later LICENSE (the license was listed in Phase 1 but missing)
- checkpoints rewritten to reflect actual state and to say plainly which
  migration-plan phases belong to the consumer repos rather than here

Fixes a real gap found by the proof-of-fit: composeDecisions kept only the
first decision's evidence, so an object governed by several targets lost the
evidence that drove its verdict. Evidence now merges — counts summed,
contributor lists unioned, flags or-ed.

556 tests; lint, typecheck, and per-package type build clean.

packages/core/test/adapter.test.js

@@ -0,0 +1,131 @@
+import { describe, expect, it } from "vitest";
+
+import {
+  collectTargets,
+  createApplicationAdapter,
+  evaluateObject,
+  evaluateObjects,
+} from "../src/adapter.js";
+import { createNeutralDecision } from "../src/policy.js";
+
+const SELLER = "d4".repeat(32);
+const EVENT_ID = "1b".repeat(32);
+
+/** @type {import('../src/adapter.js').GovernanceApplicationAdapter<any>} */
+const adapter = createApplicationAdapter({
+  applicationId: "test-app",
+  toTargets: (object) => [
+    { type: "user", pubkey: object.author },
+    { type: "event", id: object.id, author: object.author },
+  ],
+  getPrimaryTargetKey: (object) => `event:${object.id}`,
+});
+
+const object = { id: EVENT_ID, author: SELLER };
+
+/** Build an evaluator that returns a fixed visibility per target type. */
+const evaluatorFor = (byType) => (target) => {
+  const decision = createNeutralDecision({ key: `${target.type}` });
+  const effect = byType[target.type];
+  if (effect) {
+    decision.visibility.effect = effect;
+  }
+  return decision;
+};
+
+describe("createApplicationAdapter", () => {
+  it("accepts a complete adapter", () => {
+    expect(adapter.applicationId).toBe("test-app");
+  });
+
+  it("rejects a missing applicationId", () => {
+    expect(() =>
+      createApplicationAdapter(/** @type {any} */ ({ toTargets: () => [], getPrimaryTargetKey: () => "" })),
+    ).toThrow(/applicationId/);
+  });
+
+  it("rejects a missing toTargets", () => {
+    expect(() =>
+      createApplicationAdapter(/** @type {any} */ ({ applicationId: "a", getPrimaryTargetKey: () => "" })),
+    ).toThrow(/toTargets/);
+  });
+
+  it("rejects a missing getPrimaryTargetKey", () => {
+    expect(() =>
+      createApplicationAdapter(/** @type {any} */ ({ applicationId: "a", toTargets: () => [] })),
+    ).toThrow(/getPrimaryTargetKey/);
+  });
+
+  it("rejects a non-object", () => {
+    expect(() => createApplicationAdapter(/** @type {any} */ (null))).toThrow(/must be an object/);
+  });
+});
+
+describe("evaluateObject", () => {
+  it("keeps the strictest verdict reaching the object", () => {
+    const decision = evaluateObject(object, adapter, evaluatorFor({ user: "hide" }));
+    expect(decision.visibility.effect).toBe("hide");
+  });
+
+  it("is unaffected by which target was most severe when reporting identity", () => {
+    const decision = evaluateObject(object, adapter, evaluatorFor({ user: "hide" }));
+    expect(decision.key).toBe(`event:${EVENT_ID}`);
+  });
+
+  it("allows an object when no target objects", () => {
+    expect(evaluateObject(object, adapter, evaluatorFor({})).visibility.effect).toBe("allow");
+  });
+
+  it("escalates from any contributing target", () => {
+    expect(
+      evaluateObject(object, adapter, evaluatorFor({ event: "deny" })).visibility.effect,
+    ).toBe("deny");
+  });
+
+  it("filters out invalid targets the adapter emits", () => {
+    const loose = createApplicationAdapter({
+      applicationId: "a",
+      toTargets: () => [
+        /** @type {any} */ ({ type: "user", pubkey: "junk" }),
+        { type: "user", pubkey: SELLER },
+      ],
+      getPrimaryTargetKey: () => "user:x",
+    });
+    expect(() => evaluateObject(object, loose, evaluatorFor({}))).not.toThrow();
+  });
+
+  it("throws when an adapter produces no usable targets", () => {
+    const broken = createApplicationAdapter({
+      applicationId: "broken",
+      toTargets: () => [],
+      getPrimaryTargetKey: () => "x",
+    });
+    expect(() => evaluateObject(object, broken, evaluatorFor({}))).toThrow(/no valid targets/);
+  });
+});
+
+describe("evaluateObjects", () => {
+  it("keys results by primary target", () => {
+    const results = evaluateObjects([object], adapter, evaluatorFor({}));
+    expect(results.has(`event:${EVENT_ID}`)).toBe(true);
+  });
+
+  it("handles an empty list", () => {
+    expect(evaluateObjects([], adapter, evaluatorFor({})).size).toBe(0);
+  });
+});
+
+describe("collectTargets", () => {
+  it("deduplicates shared targets across objects", () => {
+    const targets = collectTargets(
+      [object, { id: "2c".repeat(32), author: SELLER }],
+      adapter,
+    );
+    // Two events plus one shared author.
+    expect(targets).toHaveLength(3);
+  });
+
+  it("returns nothing for an empty list", () => {
+    expect(collectTargets([], adapter)).toEqual([]);
+  });
+});

packages/core/test/evidence.test.js

@@ -1,6 +1,11 @@
 import { describe, expect, it } from "vitest";
 
-import { createEmptyEvidence, freezeEvidence, redactEvidence } from "../src/evidence.js";
+import {
+  createEmptyEvidence,
+  freezeEvidence,
+  mergeEvidence,
+  redactEvidence,
+} from "../src/evidence.js";
 
 const populated = () => ({
   ...createEmptyEvidence(),
@@ -71,3 +76,34 @@ describe("redactEvidence", () => {
     expect(redacted.trustedReportsByCategory).toEqual({ nudity: 1, spam: 2 });
   });
 });
+
+describe("mergeEvidence", () => {
+  it("sums counts across targets", () => {
+    const merged = mergeEvidence([populated(), populated()]);
+    expect(merged.trustedReportTotal).toBe(6);
+    expect(merged.trustedReportsByCategory.spam).toBe(4);
+  });
+
+  it("unions contributor lists without duplicating", () => {
+    const merged = mergeEvidence([populated(), populated()]);
+    expect(merged.trustedReporterPubkeys).toEqual(["aa", "bb", "cc"]);
+  });
+
+  it("ors the boolean flags", () => {
+    const denied = { ...createEmptyEvidence(), userDenied: true };
+    const blocked = { ...createEmptyEvidence(), personalBlock: true };
+    const merged = mergeEvidence([denied, blocked]);
+    expect(merged.userDenied).toBe(true);
+    expect(merged.personalBlock).toBe(true);
+    expect(merged.eventDenied).toBe(false);
+  });
+
+  it("tolerates empty and malformed input", () => {
+    expect(mergeEvidence([]).trustedReportTotal).toBe(0);
+    expect(mergeEvidence(/** @type {any} */ ([null])).trustedReportTotal).toBe(0);
+  });
+
+  it("returns sorted, stable output", () => {
+    expect(mergeEvidence([populated()])).toEqual(mergeEvidence([populated()]));
+  });
+});