feat: local HAL provider + zero-config viem ERC-8004 client (C→A milestone)

README.md

@@ -46,9 +46,9 @@ ERC-8004 defines three composable trust mechanisms; HyperDAG ships one curated d
 
 | ERC-8004 mechanism | HyperDAG default | How it works |
 |---|---|---|
-| **Reputation** (delegated trust via on-chain attestations) | `IReputation` → `@hyperdag/reputation-zkp` | Per-agent RepID 0–10,000; writes go to the canonical `ReputationRegistry` (live above). Optional ZKP RepID circuit (Plonky3) for privacy-preserving score proofs. |
+| **Reputation** (delegated trust via on-chain attestations) | `IReputation` → `@hyperdag/reputation-zkp` | Per-agent RepID 0–10,000; writes go to the canonical `ReputationRegistry` (live above). Selective-disclosure / private-ownership proofs via a Plonky3 STARK range-check today; the **roadmap-V2** circuit that binds the proof to the actual RepID-derivation transcript is in active development. |
 | **Validation** (independent re-execution / cross-check) | `IValidation` → `@hyperdag/validation-trinity` | BFT validator set with HITL graduation; cross-LLM agreement check (Phase 1.5) for factual / time-sensitive prompts; `IHallucination` veto sits in the same chain. |
-| **TEE Attestation** (verifiable execution receipts) | `IValidation` extension *(roadmap V2)* | The ZKP RepID circuit provides a verifiable-attestation flavor today; first-class TEE-backed ValidationRegistry support is roadmap (see V2 below). |
+| **TEE Attestation** (verifiable execution receipts) | `IValidation` extension *(roadmap V2)* | First-class TEE-backed ValidationRegistry support is roadmap (see V2 below). The Plonky3 STARK in `@hyperdag/reputation-zkp` today proves a narrow range claim (`repid > threshold`); binding the proof to the agent decision + HAL signals is also V2. |
 
 ---
 
@@ -96,7 +96,7 @@ HDP is not a heavy wrapper. It is a lightweight kernel defining clean versioned
 | Interface | Default | Wraps |
 | :--- | :--- | :--- |
 | `IIdentity` | `@hyperdag/identity-erc8004` | ERC-8004 IdentityRegistry |
-| `IReputation` | `@hyperdag/reputation-zkp` | ZKP RepID |
+| `IReputation` | `@hyperdag/reputation-zkp` | On-chain RepID via ERC-8004 ReputationRegistry; ZKP for private-ownership / range proofs (Plonky3, V1 today — full V2 binds to RepID transcript) |
 | `IValidation` | `@hyperdag/validation-trinity` | BFT validators (with HITL graduation) |
 | `IPayment` | `@hyperdag/payment-x402` | x402 |
 | `ILinkage` | `@hyperdag/linkage-registry` | HDP Linkage Registry (inverse-stake curve) |
@@ -115,15 +115,15 @@ graph TD
     Node2 & Node3 --> Node4{Merkle Hash}
     Node4 -->|ERC-8004| Chain[(HyperDAG Ledger)]
 
-    subgraph "Privacy Layer"
-    Chain --> ZKP[ZKP RepID Circuit]
-    ZKP --> Creds[Sovereign Credentials]
+    subgraph "Privacy Layer (V1: range-check today; V2: bound to RepID transcript)"
+    Chain --> ZKP[Plonky3 STARK Circuit]
+    ZKP --> Creds[Selective-disclosure proofs]
     end
 ```
 
 ### Core building blocks
 - **Merkle DAG** — content-addressed, append-only verifiable state.
-- **ZKP RepID** — privacy-preserving reputation proofs (Plonky3, BabyBear field, Poseidon2).
+- **ZKP for private ownership** — Plonky3 STARK (BabyBear field, Keccak FRI) range-check today; roadmap-V2 circuit binds the proof to the agent decision + HAL signals + RepID-delta derivation.
 - **[ERC-8004](https://ethereum-magicians.org/t/erc-8004-trustless-agents/25098)** — standards-based identity + reputation for autonomous agents.
 - **[x402](https://github.com/x402-rs/x402-rs)** — agent-to-agent micropayments.
 - **[Plonky3](https://github.com/Plonky3/Plonky3)** — STARK proving, no trusted setup, fast browser verification.
@@ -136,7 +136,7 @@ graph TD
 |---|---|---|
 | **V1 — Live today (Base Sepolia)** | shipping now | Six-interface modular kernel · `@hyperdag/protocol@0.1.0-alpha` on npm · IdentityRegistry + ReputationRegistry writing on Base Sepolia (4 agents, 32 attestations) · HAL pipeline + cross-LLM agreement · x402 payments. |
 | **V1.5 — User-managed permission guardrails** | 1–2 weeks | Telegram (and later email/discord/webhook) alerts when an agent attempts an action outside its lane. Six RepID-derived permission tiers (Probationary → Architect) map score to capability. Substrate is live; client SDK lands at install. |
-| **V2 — Mainnet** | Q2 2026 | Canonical registries on Base mainnet · TEE-backed ValidationRegistry path · ZKP-federated learning (bilateral benefit) · expanded validator-set diversity. |
+| **V2 — Mainnet** | Q2 2026 | Canonical registries on Base mainnet · TEE-backed ValidationRegistry path · **ZKP RepID circuit bound to agent decision + HAL signals + RepID-delta transcript (extension of today's Plonky3 range-check)** · ZKP-federated learning (bilateral benefit) · expanded validator-set diversity. |
 
 See [GOVERNANCE_ROADMAP.md](GOVERNANCE_ROADMAP.md) for the bootstrap-to-community handover timeline.
 

packages/defaults/hallucination-hal-local/README.md

@@ -0,0 +1,74 @@
+# @hyperdag/hallucination-hal-local
+
+**Status:** Internal-only. `private: true`. **Do NOT npm publish without Sean's explicit approval.**
+
+Local-first implementation of the `IHallucination` slot. Bundles the deterministic 5-signal extractor + canonical combiner from `repid-engine/src/hal/lib/`, so a `createHDP({})` consumer can run HAL evaluations **offline, with no remote dependency**, for the C→A milestone (D-017).
+
+## Why private
+
+The HAL signal-extraction formula and weighting are part of HDP's patent portfolio (P-003 — Pythagorean Comma Dissonance Detection). Per CLAUDE.md hard-stop:
+
+> RepID scoring formula T=floor(2000×log₁₀…) — never appear in public docs
+> ANFIS parameters — never in public docs
+
+This package contains the canonical 5-signal extraction formula AND the canonical combiner (Pythagorean Comma at 531441/524288). It is **safe for trinity-internal consumers** (the agents and services already inside the patent-aware codebase). It is **not** safe for public npm publication.
+
+The PUBLIC slot remains `@hyperdag/hallucination-hal`, which ships as an HTTP client + stub fallback. External consumers of `createHDP({})` continue to see that public package.
+
+## Architecture
+
+This package exports three classes:
+
+- **`LocalHALProvider`** — primary. Pure local 5-signal extraction + canonical Pythagorean-Comma combiner. Implements `IHallucination`. No network calls. The 5th signal (`agreement_score`, cross-LLM consensus) falls back to `null` when no providers are supplied — see [Cross-LLM signal](#cross-llm-signal-5th-signal) below.
+
+- **`RemoteHALProvider`** — re-export of `HALHallucinationProvider` from `@hyperdag/hallucination-hal` for API symmetry.
+
+- **`HALRouter`** — routing provider that respects `HDP_MODE`:
+  - `HDP_MODE=local` → only ever calls the local provider.
+  - `HDP_MODE=remote` → only ever calls the remote provider.
+  - `HDP_MODE=hybrid` (default) → tries local first; if the local result lands in a configurable veto-borderline zone (default `[0.20, 0.30]`), routes to remote for a second opinion. If remote is unreachable, returns the local result with `borderline_fallback: true` in `signals` (extra field).
+
+## Cross-LLM signal (5th signal)
+
+The cross-LLM `agreement_score` is the only signal that needs a model. Three paths:
+
+1. **No providers configured** → `agreement_score = null`, combiner falls back to the 4-signal formula (canonical `score.ts` already handles this branch).
+2. **BYOK providers** → caller passes provider configs in `evaluate(request, { providers, embeddingClient })`. Same shape as `HALContext.providers` in the repid-engine source.
+3. **Remote fallback** → `HALRouter` with `HDP_MODE=hybrid` will get cross-LLM coverage from the remote service when borderline.
+
+This package does **not** bundle a small local model. That would make the install size unreasonable. State of art: shipping local cross-LLM verification needs a 1-7B-param judge model, which is a 1-4 GB tarball minimum. Out of scope tonight; **honest fallback** to BYOK or remote.
+
+## Usage
+
+```ts
+import { createHDP } from '@hyperdag/protocol';
+import { HALRouter } from '@hyperdag/hallucination-hal-local';
+
+const hdp = createHDP({
+  overrides: {
+    hallucination: new HALRouter({ mode: 'hybrid' }),
+  },
+});
+
+const result = await hdp.hallucination.evaluate({
+  prompt: 'What is the boiling point of water at sea level?',
+  output: 'It boils at 100°C at sea level.',
+  context: { domain: 'physics', certainty: 0.99 },
+});
+```
+
+## Divergence from remote (A/B)
+
+The local provider matches the remote provider byte-for-byte on the deterministic 4 signals (same constants, same regex hit-lists, same Jaccard ontology overlap). The 5th signal (`agreement_score`) is the only divergence:
+
+| Mode | Where `agreement_score` comes from |
+|---|---|
+| Local, no providers | `null` (combiner falls back to 4-signal formula) |
+| Local, BYOK providers | live LLM calls from the caller's process |
+| Remote | live LLM calls from `repid-engine` (orchestrated) |
+
+For factual / time-sensitive prompts, local-no-providers will produce a different `hal_score` than remote, because remote always runs cross-LLM. **This divergence is documented in the A/B test results in the sprint report.**
+
+## License
+
+See `LICENSE` at the repo root. This package is Apache-2.0 in license terms but `private: true` in `package.json` so the npm registry refuses to publish it.

packages/defaults/hallucination-hal-local/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "@hyperdag/hallucination-hal-local",
+  "version": "0.1.0-internal",
+  "private": true,
+  "description": "Local HAL provider — deterministic 5-signal extraction + canonical combiner. Internal-only. Public npm publish requires Sean's explicit approval per CLAUDE.md hard-stop on HAL signal-extraction formula + weighting (HAEE / ANFIS / P-003 patent portfolio).",
+  "license": "SEE LICENSE IN LICENSE",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "test": "node --test --import tsx tests/*.test.ts"
+  },
+  "peerDependencies": {
+    "@hyperdag/interfaces": "*",
+    "@hyperdag/hallucination-hal": "*"
+  },
+  "devDependencies": {
+    "typescript": "^5.5.0",
+    "tsx": "^4.0.0"
+  },
+  "keywords": [
+    "hyperdag",
+    "hal",
+    "hallucination",
+    "internal"
+  ]
+}

packages/defaults/hallucination-hal-local/src/constants.ts

@@ -0,0 +1,92 @@
+/**
+ * HAL constants — ported verbatim from repid-engine/src/hal/lib/constants.ts.
+ *
+ * SACRED CONSTANTS — DO NOT MUTATE.
+ *
+ * Patent-load-bearing — this file is the reason the entire package is marked
+ * `private: true` in package.json. The HAL_PYTHAGOREAN_COMMA ratio, the
+ * formula weights, and the canonical signal field names are all part of
+ * HDP's patent portfolio (P-003). Public npm publish requires Sean's
+ * explicit approval per CLAUDE.md hard-stop.
+ *
+ * To preserve byte-equivalence with the production HAL, every constant here
+ * is a verbatim copy of the repid-engine source. Future drift between
+ * repid-engine and this package would compromise the A/B equivalence guarantee
+ * documented in README.md.
+ */
+
+export const HAL_PYTHAGOREAN_COMMA: number = 531441 / 524288;
+
+export const HAL_FORMULA_WEIGHTS = {
+  harm: 0.4,
+  epistemic: 0.3,
+  evidence: 0.2,
+  scope: 0.1,
+} as const;
+
+export const HAL_DEFAULT_VETO_THRESHOLD: number = 0.25;
+export const HAL_CONSTITUTIONAL_BLOCK_THRESHOLD: number = 0.48;
+
+export const COMMA_BFT_THRESHOLDS = {
+  vetoGap: 0.05,
+  vetoAvg: 0.85,
+  majorGap: 0.10,
+  majorAvg: 0.75,
+  minorGap: 0.15,
+} as const;
+
+export const COMMA_BAND_TIGHT_THRESHOLD: number = 0.99;
+export const COMMA_BAND_LOOSE_THRESHOLD: number = 0.95;
+
+/**
+ * Domain ontology vocabularies. High-level definition only — caller can
+ * supply additional/custom ontologies via context.
+ */
+export const DEFAULT_DOMAIN_ONTOLOGIES: Record<string, string[]> = {
+  'cre-underwriting': [
+    'cap rate', 'noi', 'vacancy', 'absorption', 'ltv', 'dscr', 'irr',
+    'cash-on-cash', 'basis points', 'underwriting', 'class a', 'class b',
+    'industrial', 'office', 'retail', 'multifamily', 'operating expenses',
+    'gross rent', 'debt service', 'net operating income',
+  ],
+  'compliance': [
+    'regulation', 'statute', 'compliance', 'audit', 'disclosure', 'fiduciary',
+    'sec', 'finra', 'gdpr', 'ccpa', 'ai act', 'liability', 'mandate',
+    'enforcement', 'violation', 'risk management', 'governance',
+  ],
+  'finance': [
+    'revenue', 'ebitda', 'margin', 'yield', 'return', 'risk', 'portfolio',
+    'asset', 'liability', 'equity', 'debt', 'interest rate', 'inflation',
+    'basis', 'spread', 'valuation', 'cash flow', 'projection',
+  ],
+  'technical': [
+    'algorithm', 'model', 'training', 'inference', 'parameter', 'neural',
+    'circuit', 'hash', 'proof', 'contract', 'token', 'consensus',
+    'validation', 'cryptography', 'protocol', 'architecture', 'implementation',
+  ],
+  'legal': [
+    'contract', 'clause', 'covenant', 'warranty', 'indemnification', 'lien',
+    'title', 'easement', 'encumbrance', 'jurisdiction', 'statute', 'precedent',
+  ],
+};
+
+export const OVERCONFIDENCE_MARKERS: readonly string[] = [
+  'guaranteed', 'certain', 'definitive', 'proven', 'fact',
+  'always', 'never', 'impossible', 'must', 'will definitely',
+  'risk-free', 'no risk', '100%', 'without doubt',
+  'everyone knows', 'obviously', 'clearly', 'undeniably',
+];
+
+/**
+ * Note the duplicate `approximately` at index 0 and again at the tail.
+ * This is preserved verbatim from the pre-extraction implementation
+ * (`src/services/hal-signals.ts:52-57` at HEAD `204cfcb`). Per repid-engine
+ * sprint hard rule #7 (no semantic changes to HAL behavior), this
+ * duplicate is preserved here too so A/B equivalence holds.
+ */
+export const EPISTEMIC_HEDGES: readonly string[] = [
+  'approximately', 'roughly', 'around', 'may', 'might', 'could',
+  'likely', 'probably', 'suggest', 'indicate', 'appear', 'seem',
+  'estimate', 'projection', 'forecast', 'assumption', 'according to',
+  'based on', 'as of', 'reported', 'approximately',
+];

packages/defaults/hallucination-hal-local/src/extract.ts

@@ -0,0 +1,90 @@
+/**
+ * Path A 5-signal HAL extractor — pure, deterministic, no I/O.
+ *
+ * Ported verbatim from repid-engine/src/hal/lib/extract.ts (commit
+ * 204cfcbe93f85f8cb0ccdc969d2cc4003129c1db). Per the repid-engine sprint
+ * hard rules #7 + #8 forbidding behavior tuning, no edits beyond the import
+ * paths. The 369-assertion regression test in repid-engine holds the line
+ * on byte-equivalence.
+ */
+
+import {
+  DEFAULT_DOMAIN_ONTOLOGIES,
+  EPISTEMIC_HEDGES,
+  OVERCONFIDENCE_MARKERS,
+} from './constants.js';
+import type { ExtractInput, NativeHALSignals } from './types.js';
+
+export function extractHALSignals(input: ExtractInput): NativeHALSignals {
+  const { text: claimText, domain, certainty } = input;
+  const ontologies = input.domainOntologies
+    ? { ...DEFAULT_DOMAIN_ONTOLOGIES, ...input.domainOntologies }
+    : DEFAULT_DOMAIN_ONTOLOGIES;
+
+  const text = claimText.toLowerCase();
+  const words = text.split(/\s+/);
+  const wordCount = words.length;
+
+  // Signal 1: harm_probability
+  const overconfidenceCount = OVERCONFIDENCE_MARKERS
+    .filter(k => text.includes(k)).length;
+  const specificNumbers = (
+    text.match(/\d+\.?\d*\s*(%|percent|basis|bps|billion|million)/g) || []
+  ).length;
+  const harm_probability = Math.min(
+    1,
+    (overconfidenceCount * 0.18) +
+    (specificNumbers * 0.08) +
+    (certainty > 0.92 && overconfidenceCount > 0 ? 0.2 : 0),
+  );
+
+  // Signal 2: epistemic_uncertainty
+  const hedgeCount = EPISTEMIC_HEDGES
+    .filter(k => text.includes(k)).length;
+  const hedgeDensity = hedgeCount / Math.max(wordCount / 8, 1);
+  let certaintyHedgeMismatch =
+    certainty > 0.88 && hedgeCount === 0 ? 0.35 : 0;
+
+  if (domain === 'mathematics' || domain === 'cryptography') {
+    certaintyHedgeMismatch *= 0.30;
+  }
+
+  let epistemic_uncertainty = Math.min(
+    1,
+    Math.max(0, 0.45 - (hedgeDensity * 0.25) + certaintyHedgeMismatch),
+  );
+
+  if (domain === 'mathematics' || domain === 'cryptography') {
+    epistemic_uncertainty *= 0.15;
+  }
+
+  // Signal 3: evidence_quality
+  const hasNumbers = /\d+/.test(text);
+  const hasTemporalRef = /\b(20\d\d|q[1-4]|january|february|march|april|may|june|july|august|september|october|november|december)\b/i.test(text);
+  const hasProperNouns = /\b[A-Z][a-z]{2,}(\s[A-Z][a-z]{2,})+/.test(claimText);
+  const lengthScore = Math.min(1, wordCount / 40);
+  const evidence_quality = Math.min(
+    1,
+    (hasNumbers ? 0.25 : 0) +
+    (hasTemporalRef ? 0.20 : 0) +
+    (hasProperNouns ? 0.15 : 0) +
+    (lengthScore * 0.40),
+  );
+
+  // Signal 4: scope_appropriateness — Jaccard-like overlap with domain ontology.
+  const ontology = ontologies[domain] ?? ontologies['finance'] ?? [];
+  const matchCount = ontology
+    .filter(term => text.includes(term.toLowerCase())).length;
+  const scope_appropriateness = Math.min(
+    1,
+    matchCount / Math.max(ontology.length * 0.25, 1),
+  );
+
+  return {
+    harm_probability,
+    epistemic_uncertainty,
+    evidence_quality,
+    scope_appropriateness,
+    certainty_at_claim: certainty,
+  };
+}

packages/defaults/hallucination-hal-local/src/index.ts

@@ -0,0 +1,36 @@
+/**
+ * @hyperdag/hallucination-hal-local — internal local HAL provider.
+ *
+ * See README.md for the publish-gate constraints. `private: true`.
+ */
+
+export { LocalHALProvider } from './providers.js';
+export type { LocalHALProviderConfig } from './providers.js';
+
+export { HALRouter } from './router.js';
+export type { HALRouterConfig, HDPMode } from './router.js';
+
+// Re-export the remote provider under a clear alias so consumers can name
+// what they're getting.
+export { HALHallucinationProvider as RemoteHALProvider } from '@hyperdag/hallucination-hal';
+
+// Surface the native types + extractor so power users can drive the local
+// extractor directly without the IHallucination wrapper.
+export { extractHALSignals } from './extract.js';
+export { computeHALScore } from './score.js';
+export type {
+  NativeHALSignals,
+  ExtractInput,
+  LocalHALEvaluateOptions,
+  CommaSeverity,
+  AgreementZone,
+  StrictnessLevel,
+} from './types.js';
+
+// Surface the constants (read-only) so consumers can verify they're using
+// the canonical values.
+export {
+  HAL_PYTHAGOREAN_COMMA,
+  HAL_FORMULA_WEIGHTS,
+  HAL_DEFAULT_VETO_THRESHOLD,
+} from './constants.js';