Implement Williams Bound HotpathPolicy foundation

[Copilot]

• P0-F1: Implement core/HotpathPolicy.ts with computeCapacity, computeSalience, deriveTierQuotas, deriveCommunityQuotas, and frozen DEFAULT_HOTPATH_POLICY
• P0-F2: Add tests/HotpathPolicy.test.ts with full test coverage (26 tests: sublinear growth, monotonicity, edge inputs, tier quota sums, community quotas, salience determinism/clamping)
• P0-F3: Extend core/types.ts with PageActivity, HotpathEntry, TierQuotas interfaces and hotpath method signatures on MetadataStore
• P0-F4: Extend storage/IndexedDbMetadataStore.ts with hotpath_index and page_activity object stores + implement all six hotpath methods
• P0-F4 tests: Extend tests/Persistence.test.ts with hotpath store tests (11 tests: put/get/evict cycle, page activity, resident count)
• All 152 tests pass (14 test files), lint clean, build clean, guard:model-derived clean
• Code review feedback: removed unreachable dead branch in deriveCommunityQuotas

Original prompt

---

This section details on the original issue you should resolve

<issue_title>P0-F: Williams Bound Policy Foundation (BLOCKS: all hotpath-aware modules)</issue_title>
<issue_description>Why: The HotpathPolicy and SalienceEngine are the central source of truth for the Williams Bound architecture. Every subsequent module (ingest, query, hierarchy, Daydreamer) depends on them. Implementing these first ensures the bound is enforced from day one rather than retrofitted.

• P0-F1: Implement core/HotpathPolicy.ts

  • computeCapacity(graphMass: number): number — H(t) = ⌈c · √(t · log₂(1+t))⌉
  • computeSalience(hebbianIn: number, recency: number, queryHits: number, weights?: SalienceWeights): number — σ = α·H_in + β·R + γ·Q
  • deriveTierQuotas(capacity: number, quotaRatios?: TierQuotaRatios): TierQuotas — allocate H(t) across shelf/volume/book/page tiers
  • deriveCommunityQuotas(tierBudget: number, communitySizes: number[]): number[] — proportional with min(1) guarantee
  • Export a frozen DEFAULT_HOTPATH_POLICY object containing all constants: c = 0.5, α = 0.5, β = 0.3, γ = 0.2, q_s = 0.10, q_v = 0.20, q_b = 0.20, q_p = 0.50
  • Keep strictly separate from core/ModelDefaults.ts (policy-derived ≠ model-derived)

• P0-F2: Add HotpathPolicy test coverage (tests/HotpathPolicy.test.ts)

  • H(t) grows sublinearly: verify H(10_000) / 10_000 < H(1_000) / 1_000
  • H(t) is monotonically non-decreasing over a representative range: verify H(t+1) >= H(t) for each t in [0, 1, 2, 10, 100, 1_000, 10_000, 100_000]
  • H(t) is a finite integer ≥ 1 for edge inputs: t = 0, t = 1, t = Number.MAX_SAFE_INTEGER; result must never be NaN, Infinity, or < 1
  • Derived tier-quota counts sum exactly to capacity: deriveTierQuotas(cap).shelf + .volume + .book + .page === cap for cap in [1, 10, 100, 1_000]
  • Community quota counts sum exactly to tier_budget: sum(deriveCommunityQuotas(budget, sizes)) === budget for representative (budget, sizes) inputs including edge cases (budget = 0, empty sizes array, budget < sizes.length)
  • Community quotas never produce NaN, Infinity, or negative values for any valid input, including sizes with a single community or all equal sizes
  • Salience is deterministic for same inputs
  • Salience clamps output to a finite number: never NaN or Infinity for extreme weight or hit-count values

• P0-F3: Extend core/types.ts

  • Add PageActivity interface: { pageId: Hash; queryHitCount: number; lastQueryAt: string; communityId?: string }
  • Add HotpathEntry interface: { entityId: Hash; tier: 'shelf' | 'volume' | 'book' | 'page'; salience: number; communityId?: string }
  • Add TierQuotas type: { shelf: number; volume: number; book: number; page: number }
  • Add hotpath method signatures to MetadataStore interface:
    • putHotpathEntry(entry: HotpathEntry): Promise<void>
    • getHotpathEntries(tier?: HotpathEntry['tier']): Promise<HotpathEntry[]>
    • evictWeakest(tier: HotpathEntry['tier'], communityId?: string): Promise<void>
    • getResidentCount(): Promise<number>
    • putPageActivity(activity: PageActivity): Promise<void>
    • getPageActivity(pageId: Hash): Promise<PageActivity | undefined>

• P0-F4: Extend storage/IndexedDbMetadataStore.ts

  • Add hotpath_index object store keyed by entityId; secondary index by tier
  • Add page_activity object store keyed by pageId
  • Implement all six new MetadataStore hotpath methods
  • Extend tests/Persistence.test.ts with hotpath store tests:
    • put/get/evict cycle for HotpathEntry
    • put/get for PageActivity
    • getResidentCount returns correct value after multiple puts

Exit Criteria: HotpathPolicy module passes all tests; types.ts has hotpath interfaces; IndexedDB hotpath stores are implemented and tested.</issue_description>

Comments on the Issue (you are @copilot in this section)

• Fixes P0-F: Williams Bound Policy Foundation (BLOCKS: all hotpath-aware modules) #17

---

🔒 GitHub Advanced Security automatically protects Copilot coding agent pull requests. You can protect all pull requests by enabling Advanced Security for your repositories. Learn more about Advanced Security.

[Copilot]

Pull request overview

Implements the Williams Bound hotpath policy foundation and adds IndexedDB persistence primitives for hotpath state, enabling future hotpath-aware modules (ingest/query/hierarchy/Daydreamer) to share a single policy + storage substrate.

Changes:

• Added core/HotpathPolicy.ts (capacity, salience, tier quotas, community quotas) plus DEFAULT_HOTPATH_POLICY.
• Extended core/types.ts with hotpath/page-activity types and new MetadataStore hotpath APIs.
• Upgraded storage/IndexedDbMetadataStore.ts to DB v2 with new hotpath_index and page_activity stores and corresponding CRUD/eviction methods; added unit tests.

Reviewed changes

Copilot reviewed 5 out of 6 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Description
core/HotpathPolicy.ts	Adds Williams Bound capacity/salience/quota utilities and default policy constants.
core/types.ts	Introduces HotpathEntry, PageActivity, TierQuotas and new MetadataStore hotpath method signatures.
storage/IndexedDbMetadataStore.ts	Bumps IndexedDB schema to v2 and implements hotpath/page-activity storage + eviction.
tests/HotpathPolicy.test.ts	Adds unit coverage for capacity/salience/quota logic and edge cases.
tests/Persistence.test.ts	Adds IndexedDB persistence tests for hotpath entries and page activity.
package-lock.json	Adds npm lockfile (not described in PR text).

[devlux76]

@copilot Please fix using your best judgement given the docs, this might be a place where the docs didn't quite adequately specify or it might be an error in the implementation. In any event please fix it the best you can.

[Copilot]

Removed the dead branch in c65bbf1. The remaining < 0 condition was unreachable because when budget < n, minPerCommunity is set to 0, making remaining = budget ≥ 0. The budget < n case is already handled correctly by the proportional largest-remainder distribution that follows (each community starts at 0 and the budget slots are distributed proportionally by size).