@holoscript/plugin-holonews 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025-2026 HoloScript Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/package.json

@@ -0,0 +1,15 @@
+{
+  "name": "@holoscript/plugin-holonews",
+  "version": "1.0.0",
+  "description": "HoloNews verifiable-claim display primitive (@claim_kiosk trait, proof-adjacency guard)",
+  "main": "src/index.mjs",
+  "type": "module",
+  "peerDependencies": {
+    "@holoscript/core": ">=8.0.0"
+  },
+  "license": "MIT",
+  "scripts": {
+    "test": "vitest run --passWithNoTests",
+    "test:coverage": "vitest run --coverage --passWithNoTests"
+  }
+}

package/src/index.mjs

@@ -0,0 +1,41 @@
+/**
+ * @holoscript/plugin-holonews
+ *
+ * HoloNews Plugin — verifiable-claim news layer for HoloLand.
+ *
+ * Phase 0 surface:
+ *   - @claim_kiosk trait: in-zone proof-display primitive (T-NEWS-KIOSK)
+ *   - ProofAdjacencyGuard: structural invariant enforcement (G.910.01 / T-NEWS-CI)
+ *
+ * The verifier is `verify_cael_trace` in packages/mcp-server/src/simulation-tools.ts.
+ * The kiosk binds its output (a CaelReceipt) to a spatial in-zone object and
+ * enforces the proof-adjacency wall across all compile targets.
+ *
+ * NOT in this phase:
+ *   - News plugin + Formalizer + GDELT firehose (Phase 2, B.4 gap #4)
+ *   - `hololand_capture_runtime_receipt` real-verification wiring (Phase 1, B.4 gap #2)
+ *   - Durable world content (Phase 1, B.4 gap #3)
+ *   - Stubbed hololandRoutes wiring (Phase 2, B.4 gap #5)
+ */
+
+export {
+  createClaimKioskHandler,
+  buildCaelReceipt,
+  defaultClaimKioskConfig,
+} from './traits/claim-kiosk-trait.mjs';
+
+export {
+  resolveProofAdjacencyPolicy,
+  auditReceiptForWallInvariant,
+  buildKioskDisplayModel,
+} from './traits/proof-adjacency-guard.mjs';
+
+import { createClaimKioskHandler } from './traits/claim-kiosk-trait.mjs';
+
+export const pluginMeta = {
+  name: '@holoscript/plugin-holonews',
+  version: '1.0.0',
+  traits: ['claim_kiosk'],
+  handlers: [createClaimKioskHandler()],
+  description: 'HoloNews verifiable-claim display primitive for HoloLand in-zone objects.',
+};

package/src/traits/claim-kiosk-trait.mjs

@@ -0,0 +1,192 @@
+/**
+ * ClaimKioskTrait — pure ESM implementation of the @claim_kiosk trait handler.
+ *
+ * Binds a CAEL receipt to a renderable in-zone HoloLand object and enforces
+ * the proof-adjacency wall invariant (G.910.01).
+ *
+ * This file is pure .mjs so it can be imported by Node-native scripts tests
+ * (scripts/__tests__/holonews-proof-adjacency.test.mjs) without a TS loader.
+ * The TypeScript wrapper (ClaimKioskTrait.ts) re-exports from this file.
+ */
+
+import {
+  buildKioskDisplayModel,
+  auditReceiptForWallInvariant,
+} from './proof-adjacency-guard.mjs';
+
+// ── defaultConfig ──────────────────────────────────────────────────────────
+
+export const defaultClaimKioskConfig = {
+  canRenderWall: true,
+  label: 'Verified Claim Kiosk',
+  showEnvelope: true,
+  loudAuditFailures: true,
+};
+
+// ── Handler factory ────────────────────────────────────────────────────────
+
+/**
+ * Create the @claim_kiosk trait handler.
+ *
+ * @returns {{ name: string, defaultConfig: object, onAttach: Function,
+ *             onDetach: Function, onUpdate: Function, onEvent: Function }}
+ */
+export function createClaimKioskHandler() {
+  return {
+    name: 'claim_kiosk',
+    defaultConfig: defaultClaimKioskConfig,
+
+    onAttach(node, _config, ctx) {
+      node.__kioskState = {
+        receipt: null,
+        displayModel: null,
+        envelopeOverrides: {},
+        idle: true,
+      };
+      ctx.emit?.('kiosk:ready');
+    },
+
+    onDetach(node, _config, ctx) {
+      delete node.__kioskState;
+      ctx.emit?.('kiosk:offline');
+    },
+
+    onUpdate(_node, _config, _ctx, _deltaMs) {
+      // Event-driven — no continuous update logic.
+    },
+
+    onEvent(node, config, ctx, event) {
+      const state = node.__kioskState;
+      if (!state) return;
+
+      // ── kiosk:receipt_bind ────────────────────────────────────────────
+      if (event.type === 'kiosk:receipt_bind') {
+        const receipt = event.payload?.receipt;
+        if (!receipt) {
+          ctx.emit?.('kiosk:error', { reason: 'receipt_bind received no receipt in payload' });
+          return;
+        }
+
+        const violations = auditReceiptForWallInvariant(receipt);
+        if (violations.length > 0 && config.loudAuditFailures) {
+          ctx.emit?.('kiosk:audit_violation', { violations, receiptId: receipt.receiptId });
+        }
+
+        const displayModel = buildKioskDisplayModel(receipt, config.canRenderWall);
+
+        state.receipt = receipt;
+        state.displayModel = displayModel;
+        state.envelopeOverrides = {};
+        state.idle = false;
+
+        ctx.emit?.('kiosk:display_ready', { displayModel });
+
+        if (displayModel.showBadge) {
+          // Badge shown — wall MUST be co-rendered (enforced by policy='badge-with-wall').
+          ctx.emit?.('kiosk:badge_render', {
+            claimText: displayModel.claimText,
+            wallText: displayModel.wallText,
+            verifyUrl: displayModel.verifyUrl,
+          });
+        } else if (displayModel.policy === 'badge-suppressed-rerun-only') {
+          ctx.emit?.('kiosk:badge_suppressed', {
+            claimText: displayModel.claimText,
+            verifyUrl: displayModel.verifyUrl,
+            reason:
+              receipt.notProvenWall == null || receipt.notProvenWall.trim() === ''
+                ? 'missing_wall_text'
+                : 'target_cannot_render_wall',
+          });
+        }
+        // policy === 'no-badge': labeled or pending — no badge event.
+        return;
+      }
+
+      // ── kiosk:envelope_update ─────────────────────────────────────────
+      if (event.type === 'kiosk:envelope_update') {
+        if (!state.receipt?.envelope) {
+          ctx.emit?.('kiosk:error', {
+            reason: 'envelope_update received but no envelope on receipt',
+          });
+          return;
+        }
+        const paramName = event.payload?.paramName;
+        const value = event.payload?.value;
+        if (paramName == null || value == null) {
+          ctx.emit?.('kiosk:error', { reason: 'envelope_update missing paramName or value' });
+          return;
+        }
+        const param = state.receipt.envelope.params.find((p) => p.name === paramName);
+        if (!param) {
+          ctx.emit?.('kiosk:error', {
+            reason: `envelope_update: unknown param "${paramName}"`,
+          });
+          return;
+        }
+        const clamped = Math.min(Math.max(value, param.min), param.max);
+        state.envelopeOverrides[paramName] = clamped;
+
+        ctx.emit?.('kiosk:envelope_changed', {
+          paramName,
+          value: clamped,
+          allOverrides: { ...state.envelopeOverrides },
+          boundaryDescription: state.receipt.envelope.boundaryDescription,
+        });
+        return;
+      }
+
+      // ── kiosk:rerun_request ───────────────────────────────────────────
+      if (event.type === 'kiosk:rerun_request') {
+        if (!state.receipt) {
+          ctx.emit?.('kiosk:error', { reason: 'rerun_request but no receipt bound' });
+          return;
+        }
+        ctx.emit?.('kiosk:rerun_initiated', {
+          verifyUrl: state.receipt.verifyUrl,
+          traceId: state.receipt.traceId,
+          envelopeOverrides: { ...state.envelopeOverrides },
+        });
+        return;
+      }
+
+      // ── kiosk:reset ───────────────────────────────────────────────────
+      if (event.type === 'kiosk:reset') {
+        state.receipt = null;
+        state.displayModel = null;
+        state.envelopeOverrides = {};
+        state.idle = true;
+        ctx.emit?.('kiosk:ready');
+      }
+    },
+  };
+}
+
+// ── buildCaelReceipt ───────────────────────────────────────────────────────
+
+/**
+ * Build a CaelReceipt from verify_cael_trace output fields plus the required
+ * human-authored claim text and not-proven wall.
+ *
+ * @param {{
+ *   receiptId: string, traceId: string, verifyUrl: string,
+ *   hashChainValid: boolean, replayValid: boolean,
+ *   claimText: string, notProvenWall: string,
+ *   sealedAt?: string,
+ *   envelope?: object,
+ * }} opts
+ */
+export function buildCaelReceipt(opts) {
+  const verdict = opts.hashChainValid && opts.replayValid ? 'proven' : 'labeled';
+  return {
+    receiptId: opts.receiptId,
+    traceId: opts.traceId,
+    verifyUrl: opts.verifyUrl,
+    verdict,
+    hashChainValid: opts.hashChainValid,
+    replayValid: opts.replayValid,
+    sealedAt: opts.sealedAt ?? new Date().toISOString(),
+    claimText: opts.claimText,
+    notProvenWall: opts.notProvenWall,
+    ...(opts.envelope != null ? { envelope: opts.envelope } : {}),
+  };
+}

package/src/traits/proof-adjacency-guard.mjs

@@ -0,0 +1,131 @@
+/**
+ * ProofAdjacencyGuard — pure ESM implementation of the proof-adjacency wall invariant.
+ *
+ * INVARIANT (G.910.01):
+ *   A "proven" badge MAY ONLY be displayed when the not-proven boundary text
+ *   (`notProvenWall`) is rendered at equal or greater prominence on the SAME
+ *   surface in the SAME viewport.
+ *
+ *   Any compile target that cannot honour this constraint MUST suppress the
+ *   badge entirely and show the claim text + re-run link only.
+ *
+ * This file is pure .mjs so it can be imported by Node-native scripts tests
+ * (scripts/__tests__/holonews-proof-adjacency.test.mjs) without a TS loader.
+ * The TypeScript wrappers (ProofAdjacencyGuard.ts) re-export from this file.
+ *
+ * FALSIFICATION CONTRACT (T-NEWS-CI):
+ *   `scripts/__tests__/holonews-proof-adjacency.test.mjs` checks every branch
+ *   of `resolveProofAdjacencyPolicy` at build time.  A CI failure there means
+ *   this invariant has been violated.
+ */
+
+/**
+ * Resolve which proof-adjacency policy applies for a given receipt and compile
+ * target capability.
+ *
+ * Pure function — no side effects, no I/O, deterministic output.
+ *
+ * @param {import('./types.js').CaelReceipt} receipt
+ * @param {boolean} canRenderWall  Whether the current compile target can co-render
+ *   the not-proven wall alongside the badge in the same viewport.
+ * @returns {import('./types.js').ProofAdjacencyPolicy}
+ */
+export function resolveProofAdjacencyPolicy(receipt, canRenderWall) {
+  // If the verdict is not proven, there is never a badge to display.
+  if (receipt.verdict !== 'proven') {
+    return 'no-badge';
+  }
+
+  // A proven verdict with no wall text means the not-proven boundary was not
+  // authored.  Without it the badge is structurally unanchored — suppress.
+  if (!receipt.notProvenWall || receipt.notProvenWall.trim() === '') {
+    return 'badge-suppressed-rerun-only';
+  }
+
+  // The target claims it can render the wall.  Trust it — but the CI test
+  // verifies that this branch is never reached without a non-empty wall.
+  if (canRenderWall) {
+    return 'badge-with-wall';
+  }
+
+  // Target cannot render the wall (OG card, social crop, etc.) — suppress.
+  return 'badge-suppressed-rerun-only';
+}
+
+/**
+ * Validate that a CaelReceipt meets the minimum requirements for the
+ * proof-adjacency invariant.
+ *
+ * Returns a list of violation strings.  Empty array means the receipt is
+ * structurally sound.
+ *
+ * @param {import('./types.js').CaelReceipt} receipt
+ * @returns {string[]}
+ */
+export function auditReceiptForWallInvariant(receipt) {
+  const violations = [];
+
+  if (receipt.verdict === 'proven') {
+    if (!receipt.notProvenWall || receipt.notProvenWall.trim() === '') {
+      violations.push(
+        `Receipt ${receipt.receiptId}: verdict is "proven" but notProvenWall is absent or empty. ` +
+          `The proof-adjacency wall cannot be rendered — badge will be suppressed on all targets.`,
+      );
+    }
+    if (!receipt.verifyUrl || !receipt.verifyUrl.startsWith('http')) {
+      violations.push(
+        `Receipt ${receipt.receiptId}: verdict is "proven" but verifyUrl is missing or invalid. ` +
+          `Readers cannot independently re-run the proof.`,
+      );
+    }
+    if (!receipt.hashChainValid) {
+      violations.push(
+        `Receipt ${receipt.receiptId}: verdict is "proven" but hashChainValid is false. ` +
+          `This is a contradictory state — the receipt is structurally corrupt.`,
+      );
+    }
+    if (!receipt.replayValid) {
+      violations.push(
+        `Receipt ${receipt.receiptId}: verdict is "proven" but replayValid is false. ` +
+          `This is a contradictory state — the receipt is structurally corrupt.`,
+      );
+    }
+  }
+
+  return violations;
+}
+
+/**
+ * Build the display model for a kiosk render from a receipt and a target
+ * capability flag.
+ *
+ * This is the single data-transformation step between a raw receipt and the
+ * in-zone object's render output.  Compile targets consume this record; they
+ * do not inspect the raw receipt directly.
+ *
+ * @param {import('./types.js').CaelReceipt} receipt
+ * @param {boolean} canRenderWall
+ * @returns {{
+ *   policy: import('./types.js').ProofAdjacencyPolicy,
+ *   claimText: string,
+ *   wallText: string | undefined,
+ *   showBadge: boolean,
+ *   verifyUrl: string | undefined,
+ *   showEnvelope: boolean,
+ *   auditViolations: string[],
+ * }}
+ */
+export function buildKioskDisplayModel(receipt, canRenderWall) {
+  const policy = resolveProofAdjacencyPolicy(receipt, canRenderWall);
+  const auditViolations = auditReceiptForWallInvariant(receipt);
+
+  return {
+    policy,
+    claimText: receipt.claimText,
+    wallText: policy === 'badge-with-wall' ? receipt.notProvenWall : undefined,
+    showBadge: policy === 'badge-with-wall',
+    verifyUrl: receipt.verdict === 'proven' ? receipt.verifyUrl : undefined,
+    showEnvelope: policy !== 'no-badge' && receipt.envelope != null,
+    auditViolations,
+  };
+}