fix(core): pin necessary consent to always-granted in state

.changeset/necessary-consent-always-granted.md

@@ -0,0 +1,5 @@
+---
+"@junctionjs/core": patch
+---
+
+fix(core): pin `necessary: true` in consent state so it is always granted and cannot be overridden

.gitignore

@@ -41,3 +41,6 @@ yarn-debug.log*
 yarn-error.log*
 .vercel
 .env*.local
+
+# Worktrees
+.worktrees/

packages/core/src/collector.test.ts

@@ -688,7 +688,7 @@ describe("Collector", () => {
       vi.advanceTimersByTime(3000);
 
       const event = (dest.transform as any).mock.calls[0][0] as JctEvent;
-      expect(event.context.consent).toEqual({ analytics: true, marketing: false });
+      expect(event.context.consent).toEqual({ necessary: true, analytics: true, marketing: false });
     });
 
     it("does not include was_queued for non-queued events", () => {
@@ -740,7 +740,7 @@ describe("Collector", () => {
 
       const event = (dest.transform as any).mock.calls[0][0] as JctEvent;
       // The consent snapshot should reflect the resolved state, not the original pending state
-      expect(event.context.consent).toEqual({ analytics: true });
+      expect(event.context.consent).toEqual({ necessary: true, analytics: true });
     });
 
     it("consent snapshot reflects state at track() time, not dispatch time", () => {
@@ -759,7 +759,7 @@ describe("Collector", () => {
 
       const event = (dest.transform as any).mock.calls[0][0] as JctEvent;
       // Event was built with the state at track() time
-      expect(event.context.consent).toEqual({ analytics: true, marketing: false });
+      expect(event.context.consent).toEqual({ necessary: true, analytics: true, marketing: false });
     });
   });
 
@@ -784,7 +784,7 @@ describe("Collector", () => {
       collector.consent({ analytics: true });
 
       expect(update).toHaveBeenCalledTimes(1);
-      expect(update).toHaveBeenCalledWith({ analytics: true });
+      expect(update).toHaveBeenCalledWith({ necessary: true, analytics: true });
     });
 
     it("calls signal update() before destination onConsent()", () => {
@@ -901,7 +901,7 @@ describe("Collector", () => {
       const collector = createCollector(options);
 
       expect(() => collector.consent({ analytics: false })).not.toThrow();
-      expect(dest.onConsent).toHaveBeenCalledWith({ analytics: false });
+      expect(dest.onConsent).toHaveBeenCalledWith({ necessary: true, analytics: false });
     });
   });
 });

packages/core/src/consent.test.ts

@@ -50,7 +50,7 @@ describe("ConsentManager", () => {
 
     it("starts with empty state when no defaults provided", () => {
       manager = createConsentManager(makeConfig());
-      expect(manager.getState()).toEqual({});
+      expect(manager.getState()).toEqual({ necessary: true });
     });
   });
 
@@ -69,7 +69,7 @@ describe("ConsentManager", () => {
       manager = createConsentManager(makeConfig({ defaultState: { analytics: false } }));
 
       manager.setState({ analytics: true });
-      expect(manager.getState()).toEqual({ analytics: true });
+      expect(manager.getState()).toEqual({ necessary: true, analytics: true });
     });
 
     it("notifies listeners on change", () => {
@@ -80,7 +80,7 @@ describe("ConsentManager", () => {
       manager.setState({ analytics: true });
 
       expect(listener).toHaveBeenCalledTimes(1);
-      expect(listener).toHaveBeenCalledWith({ analytics: true }, {});
+      expect(listener).toHaveBeenCalledWith({ necessary: true, analytics: true }, { necessary: true });
     });
 
     it("passes previous state to listeners", () => {
@@ -388,7 +388,7 @@ describe("ConsentManager", () => {
       vi.advanceTimersByTime(3500);
 
       expect(listener).toHaveBeenCalledTimes(1);
-      expect(manager.getState()).toEqual({ analytics: false, marketing: false });
+      expect(manager.getState()).toEqual({ necessary: true, analytics: false, marketing: false });
     });
 
     it("cancels fallback timer when setState() is called before timeout", () => {
@@ -410,7 +410,7 @@ describe("ConsentManager", () => {
       // Advance past fallback timeout — should NOT fire again
       vi.advanceTimersByTime(6000);
       expect(listener).toHaveBeenCalledTimes(1);
-      expect(manager.getState()).toEqual({ analytics: true, marketing: true });
+      expect(manager.getState()).toEqual({ necessary: true, analytics: true, marketing: true });
     });
 
     it("does not apply fallback when not configured", () => {

packages/core/src/consent.ts

@@ -60,7 +60,7 @@ export interface ConsentManager {
 // ─── Implementation ──────────────────────────────────────────────
 
 export function createConsentManager(config: ConsentConfig): ConsentManager {
-  let state: ConsentState = { ...config.defaultState };
+  let state: ConsentState = { necessary: true, ...config.defaultState };
   let queue: QueuedEvent[] = [];
   const listeners = new Set<ConsentListener>();
 
@@ -117,14 +117,15 @@ export function createConsentManager(config: ConsentConfig): ConsentManager {
 
       // Merge — don't replace. This allows incremental consent updates
       // (e.g., user grants analytics first, marketing later).
-      state = { ...state, ...update };
+      // "necessary" is always granted — external callers cannot override it.
+      state = { ...state, ...update, necessary: true };
 
       notify(previous);
     },
 
     reset() {
       const previous = { ...state };
-      state = { ...config.defaultState };
+      state = { necessary: true, ...config.defaultState };
       queue = [];
       notify(previous);
     },