@principles/core 1.201.0 → 1.203.0

package/dist/runtime-v2/feature-flags/__tests__/surface-guard-policy.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=surface-guard-policy.test.d.ts.map

package/dist/runtime-v2/feature-flags/__tests__/surface-guard-policy.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"surface-guard-policy.test.d.ts","sourceRoot":"","sources":["../../../../src/runtime-v2/feature-flags/__tests__/surface-guard-policy.test.ts"],"names":[],"mappings":""}

package/dist/runtime-v2/feature-flags/__tests__/surface-guard-policy.test.js

@@ -0,0 +1,246 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import { checkSurfaceGuard, isSurfaceEnabled, guardHook, guardService, getSurfaceIdForHook, getSurfaceIdForService, __resetSurfaceGuardSkipLogStateForTests, } from '../surface-guard-policy.js';
+import { PLUGIN_SURFACE_REGISTRY } from '../plugin-surface-registry.js';
+describe('surface-guard', () => {
+    beforeEach(() => {
+        // Each test starts with a clean surface-guard skip log state so the
+        // first-fire assertions are deterministic (PRI-298).
+        __resetSurfaceGuardSkipLogStateForTests();
+        vi.clearAllMocks();
+    });
+    describe('getSurfaceIdForHook', () => {
+        it('generates correct surface id without label', () => {
+            expect(getSurfaceIdForHook('before_tool_call')).toBe('hook:before_tool_call');
+        });
+        it('generates correct surface id with label', () => {
+            expect(getSurfaceIdForHook('after_tool_call', 'trajectory')).toBe('hook:after_tool_call.trajectory');
+        });
+    });
+    describe('getSurfaceIdForService', () => {
+        it('generates correct surface id for service', () => {
+            expect(getSurfaceIdForService('evolution-worker')).toBe('service:evolution-worker');
+        });
+    });
+    describe('checkSurfaceGuard', () => {
+        it('returns passed=true when registry is valid', () => {
+            const result = checkSurfaceGuard();
+            expect(result.passed).toBe(true);
+            expect(result.violations).toEqual([]);
+        });
+        it('includes enabled core surfaces', () => {
+            const result = checkSurfaceGuard();
+            expect(result.enabledCoreSurfaces.length).toBeGreaterThan(0);
+            for (const surfaceId of result.enabledCoreSurfaces) {
+                const entry = PLUGIN_SURFACE_REGISTRY.find(s => s.id === surfaceId);
+                expect(entry).toBeDefined();
+                expect(entry?.category).toBe('core');
+            }
+        });
+        it('includes disabled non-core surfaces', () => {
+            const result = checkSurfaceGuard();
+            expect(result.disabledNonCoreSurfaces.length).toBeGreaterThan(0);
+            for (const surfaceId of result.disabledNonCoreSurfaces) {
+                const entry = PLUGIN_SURFACE_REGISTRY.find(s => s.id === surfaceId);
+                expect(entry).toBeDefined();
+                expect(entry?.category).not.toBe('core');
+                expect(entry?.enabledByDefault).toBe(false);
+            }
+        });
+        it('returns violations when non-core surface is enabledByDefault', () => {
+            const result = checkSurfaceGuard();
+            const nonCoreEnabled = PLUGIN_SURFACE_REGISTRY.filter(s => s.category !== 'core' && s.enabledByDefault);
+            if (nonCoreEnabled.length > 0) {
+                expect(result.violations.length).toBeGreaterThan(0);
+            }
+        });
+    });
+    describe('isSurfaceEnabled', () => {
+        it('returns enabled=true for core surface without override', () => {
+            const result = isSurfaceEnabled('hook:before_prompt_build');
+            expect(result.enabled).toBe(true);
+            expect(result.reason).toBeUndefined();
+        });
+        it('returns enabled=false for quiet surface without override', () => {
+            const result = isSurfaceEnabled('hook:after_tool_call.trajectory');
+            expect(result.enabled).toBe(false);
+            expect(result.reason).toBeDefined();
+        });
+        it('returns reason when surface not found', () => {
+            const result = isSurfaceEnabled('hook:nonexistent_hook');
+            expect(result.enabled).toBe(false);
+            expect(result.reason).toContain('not found in registry');
+        });
+        it('allows override for quiet surface', () => {
+            const result = isSurfaceEnabled('hook:before_reset', {
+                'hook:before_reset': true,
+            });
+            expect(result.enabled).toBe(true);
+        });
+        it('ignores non-boolean override', () => {
+            const result = isSurfaceEnabled('hook:before_prompt_build', {
+                'hook:before_prompt_build': 'yes',
+            });
+            expect(result.enabled).toBe(true);
+        });
+        it('cannot disable core surface', () => {
+            const result = isSurfaceEnabled('hook:before_prompt_build', {
+                'hook:before_prompt_build': false,
+            });
+            expect(result.enabled).toBe(true);
+            expect(result.reason).toContain('core');
+        });
+        it('returns disabledReason for disabled surface', () => {
+            const result = isSurfaceEnabled('service:evolution-worker');
+            expect(result.enabled).toBe(false);
+            expect(result.reason).toContain('evolution_worker');
+        });
+    });
+    describe('guardHook', () => {
+        beforeEach(() => {
+            vi.clearAllMocks();
+        });
+        it('returns original handler for enabled surface', () => {
+            const mockHandler = vi.fn().mockReturnValue('result');
+            const guarded = guardHook('hook:before_prompt_build', undefined, mockHandler);
+            const result = guarded({}, {});
+            expect(mockHandler).toHaveBeenCalled();
+            expect(result).toBe('result');
+        });
+        it('returns no-op for disabled surface without logger', () => {
+            const mockHandler = vi.fn();
+            const guarded = guardHook('hook:after_tool_call.trajectory', undefined, mockHandler);
+            const result = guarded({}, {});
+            expect(mockHandler).not.toHaveBeenCalled();
+            expect(result).toBeUndefined();
+        });
+        it('logs when surface is disabled with logger', () => {
+            const mockLogger = { info: vi.fn(), debug: vi.fn() };
+            const mockHandler = vi.fn();
+            const guarded = guardHook('hook:after_tool_call.trajectory', mockLogger, mockHandler);
+            guarded({}, {});
+            expect(mockLogger.info).toHaveBeenCalled();
+            expect(mockHandler).not.toHaveBeenCalled();
+        });
+        it('does not log at guardHook construction time (PRI-298 / chatgpt P2)', () => {
+            const mockLogger = { info: vi.fn(), debug: vi.fn() };
+            guardHook('hook:after_tool_call.trajectory', mockLogger, vi.fn());
+            expect(mockLogger.info).not.toHaveBeenCalled();
+        });
+        it('logger undefined on first fire does not consume the one-shot slot (PRI-298 / coderabbit Major)', () => {
+            const handler1 = guardHook('hook:after_tool_call.trajectory', undefined, vi.fn());
+            handler1({}, {});
+            const mockLogger = { info: vi.fn(), debug: vi.fn() };
+            const handler2 = guardHook('hook:after_tool_call.trajectory', mockLogger, vi.fn());
+            handler2({}, {});
+            expect(mockLogger.info).toHaveBeenCalledTimes(1);
+            expect(mockLogger.info).toHaveBeenCalledWith(expect.stringContaining('[PD:surface-guard] SKIP hook:after_tool_call.trajectory'));
+            const handler3 = guardHook('hook:after_tool_call.trajectory', mockLogger, vi.fn());
+            handler3({}, {});
+            expect(mockLogger.info).toHaveBeenCalledTimes(1);
+        });
+        it('does not log for enabled surface', () => {
+            const mockLogger = { info: vi.fn(), debug: vi.fn() };
+            const mockHandler = vi.fn();
+            const guarded = guardHook('hook:before_prompt_build', mockLogger, mockHandler);
+            guarded({}, {});
+            expect(mockLogger.info).not.toHaveBeenCalled();
+        });
+        it('guards unknown surface with not-found reason', () => {
+            const mockLogger = { info: vi.fn(), debug: vi.fn() };
+            const guarded = guardHook('hook:unknown_hook', mockLogger, vi.fn());
+            guarded({}, {});
+            expect(mockLogger.info).toHaveBeenCalledWith(expect.stringContaining('not found in registry'));
+        });
+        it('logs once on first fire and stays silent on subsequent fires (PRI-298 rate-limit)', () => {
+            const mockLogger = { info: vi.fn(), debug: vi.fn() };
+            const mockHandler = vi.fn();
+            const guarded = guardHook('hook:after_tool_call.trajectory', mockLogger, mockHandler);
+            guarded({}, {});
+            expect(mockLogger.info).toHaveBeenCalledTimes(1);
+            expect(mockLogger.info).toHaveBeenCalledWith(expect.stringContaining('[PD:surface-guard] SKIP hook:after_tool_call.trajectory'));
+            for (let i = 0; i < 5; i += 1) {
+                guarded({}, {});
+            }
+            expect(mockLogger.info).toHaveBeenCalledTimes(1);
+            expect(mockHandler).not.toHaveBeenCalled();
+        });
+        it('logs first fire per surfaceId independently (one log per quiet surface)', () => {
+            const mockLogger = { info: vi.fn(), debug: vi.fn() };
+            const handler1 = guardHook('hook:after_tool_call.trajectory', mockLogger, vi.fn());
+            const handler2 = guardHook('hook:llm_output.trajectory', mockLogger, vi.fn());
+            const handler3 = guardHook('hook:subagent_spawning', mockLogger, vi.fn());
+            handler1({}, {});
+            handler2({}, {});
+            handler3({}, {});
+            expect(mockLogger.info).toHaveBeenCalledTimes(3);
+            const calls = mockLogger.info.mock.calls.map(c => String(c[0]));
+            expect(calls.some(c => c.includes('hook:after_tool_call.trajectory'))).toBe(true);
+            expect(calls.some(c => c.includes('hook:llm_output.trajectory'))).toBe(true);
+            expect(calls.some(c => c.includes('hook:subagent_spawning'))).toBe(true);
+        });
+    });
+    describe('guardService', () => {
+        beforeEach(() => {
+            vi.clearAllMocks();
+        });
+        it('returns original service for enabled surface', () => {
+            const mockService = { id: 'test-service' };
+            const result = guardService('hook:before_prompt_build', mockService);
+            expect(result).toBe(mockService);
+        });
+        it('returns null for disabled surface without logger', () => {
+            const mockService = { id: 'test-service' };
+            const result = guardService('hook:after_tool_call.trajectory', mockService);
+            expect(result).toBeNull();
+        });
+        it('logs when surface is disabled with logger', () => {
+            const mockLogger = { info: vi.fn(), debug: vi.fn() };
+            const mockService = { id: 'test-service' };
+            const result = guardService('hook:after_tool_call.trajectory', mockService, mockLogger);
+            expect(result).toBeNull();
+            expect(mockLogger.info).toHaveBeenCalledWith(expect.stringContaining('SKIP service'));
+        });
+        it('returns null for unknown surface', () => {
+            const mockService = { id: 'test-service' };
+            const result = guardService('service:nonexistent', mockService);
+            expect(result).toBeNull();
+        });
+        it('logs once per service surface on first registration (PRI-298 rate-limit)', () => {
+            const mockLogger = { info: vi.fn(), debug: vi.fn() };
+            const service = { id: 'test-service' };
+            const first = guardService('service:evolution-worker', service, mockLogger);
+            expect(first).toBeNull();
+            expect(mockLogger.info).toHaveBeenCalledTimes(1);
+            expect(mockLogger.info).toHaveBeenCalledWith(expect.stringContaining('SKIP service service:evolution-worker'));
+            guardService('service:evolution-worker', service, mockLogger);
+            guardService('service:evolution-worker', service, mockLogger);
+            expect(mockLogger.info).toHaveBeenCalledTimes(1);
+        });
+    });
+    describe('PRI-298 disabledReason copy', () => {
+        it('no quiet surface disabledReason references "Story A" or "Story A\'"', () => {
+            const quietOrNonCore = PLUGIN_SURFACE_REGISTRY.filter(s => s.category === 'quiet' || s.category === 'gone' || s.category === 'legacy_retire');
+            expect(quietOrNonCore.length).toBeGreaterThan(0);
+            for (const surface of quietOrNonCore) {
+                expect(surface.disabledReason).toBeDefined();
+                expect(surface.disabledReason).not.toMatch(/Story A/);
+                expect(surface.disabledReason).not.toMatch(/MVP\s*验收/);
+                expect(surface.disabledReason).not.toMatch(/测试任务/);
+            }
+        });
+        it('subagent/shadow hooks removed from registry (PRI-448)', () => {
+            const subagent = PLUGIN_SURFACE_REGISTRY.find(s => s.id === 'hook:subagent_spawning');
+            expect(subagent).toBeUndefined();
+        });
+        it('no quiet surface disabledReason promises a feature flag override (PRI-298 / chatgpt P2)', () => {
+            const quiet = PLUGIN_SURFACE_REGISTRY.filter(s => s.category === 'quiet');
+            expect(quiet.length).toBeGreaterThan(0);
+            for (const surface of quiet) {
+                const reason = (surface.disabledReason ?? '').toLowerCase();
+                expect(reason).not.toContain('enable via feature flag');
+                expect(reason).not.toMatch(/enable via .* override/);
+            }
+        });
+    });
+});
+//# sourceMappingURL=surface-guard-policy.test.js.map

package/dist/runtime-v2/feature-flags/__tests__/surface-guard-policy.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"surface-guard-policy.test.js","sourceRoot":"","sources":["../../../../src/runtime-v2/feature-flags/__tests__/surface-guard-policy.test.ts"],"names":[],"mappings":"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"}

package/dist/runtime-v2/feature-flags/index.d.ts

@@ -2,4 +2,6 @@ export { VALID_CATEGORIES, validateFeatureFlagRaw, computeEffectiveFlags, DEFAUL
 export type { FeatureFlagCategory, FeatureFlagDefinition, EffectiveFeatureFlags, ValidationResult, ValidationResultOk, ValidationResultErr, } from './feature-flag-contract.js';
 export { VALID_SURFACE_KINDS, VALID_MVP_CATEGORIES, PLUGIN_SURFACE_REGISTRY, validateSurfaceRegistry, getEnabledSurfaces, getSurfacesByCategory, getSurfacesByKind, findUnclassifiedSurfaces, } from './plugin-surface-registry.js';
 export type { SurfaceKind, MvpCategory, PluginSurfaceEntry, SurfaceRegistryValidationResult, } from './plugin-surface-registry.js';
+export { checkSurfaceGuard, getSurfaceIdForHook, getSurfaceIdForService, isSurfaceEnabled, guardHook, guardService, __resetSurfaceGuardSkipLogStateForTests, } from './surface-guard-policy.js';
+export type { SurfaceGuardResult, HookHandler, } from './surface-guard-policy.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/runtime-v2/feature-flags/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/runtime-v2/feature-flags/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,gBAAgB,EAChB,sBAAsB,EACtB,qBAAqB,EACrB,qBAAqB,GACtB,MAAM,4BAA4B,CAAC;AAEpC,YAAY,EACV,mBAAmB,EACnB,qBAAqB,EACrB,qBAAqB,EACrB,gBAAgB,EAChB,kBAAkB,EAClB,mBAAmB,GACpB,MAAM,4BAA4B,CAAC;AAEpC,OAAO,EACL,mBAAmB,EACnB,oBAAoB,EACpB,uBAAuB,EACvB,uBAAuB,EACvB,kBAAkB,EAClB,qBAAqB,EACrB,iBAAiB,EACjB,wBAAwB,GACzB,MAAM,8BAA8B,CAAC;AAEtC,YAAY,EACV,WAAW,EACX,WAAW,EACX,kBAAkB,EAClB,+BAA+B,GAChC,MAAM,8BAA8B,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/runtime-v2/feature-flags/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,gBAAgB,EAChB,sBAAsB,EACtB,qBAAqB,EACrB,qBAAqB,GACtB,MAAM,4BAA4B,CAAC;AAEpC,YAAY,EACV,mBAAmB,EACnB,qBAAqB,EACrB,qBAAqB,EACrB,gBAAgB,EAChB,kBAAkB,EAClB,mBAAmB,GACpB,MAAM,4BAA4B,CAAC;AAEpC,OAAO,EACL,mBAAmB,EACnB,oBAAoB,EACpB,uBAAuB,EACvB,uBAAuB,EACvB,kBAAkB,EAClB,qBAAqB,EACrB,iBAAiB,EACjB,wBAAwB,GACzB,MAAM,8BAA8B,CAAC;AAEtC,YAAY,EACV,WAAW,EACX,WAAW,EACX,kBAAkB,EAClB,+BAA+B,GAChC,MAAM,8BAA8B,CAAC;AAGtC,OAAO,EACL,iBAAiB,EACjB,mBAAmB,EACnB,sBAAsB,EACtB,gBAAgB,EAChB,SAAS,EACT,YAAY,EACZ,uCAAuC,GACxC,MAAM,2BAA2B,CAAC;AAEnC,YAAY,EACV,kBAAkB,EAClB,WAAW,GACZ,MAAM,2BAA2B,CAAC"}

package/dist/runtime-v2/feature-flags/index.js

@@ -1,3 +1,5 @@
 export { VALID_CATEGORIES, validateFeatureFlagRaw, computeEffectiveFlags, DEFAULT_FEATURE_FLAGS, } from './feature-flag-contract.js';
 export { VALID_SURFACE_KINDS, VALID_MVP_CATEGORIES, PLUGIN_SURFACE_REGISTRY, validateSurfaceRegistry, getEnabledSurfaces, getSurfacesByCategory, getSurfacesByKind, findUnclassifiedSurfaces, } from './plugin-surface-registry.js';
+// Surface guard — pure logic migrated from plugin (Stage 3)
+export { checkSurfaceGuard, getSurfaceIdForHook, getSurfaceIdForService, isSurfaceEnabled, guardHook, guardService, __resetSurfaceGuardSkipLogStateForTests, } from './surface-guard-policy.js';
 //# sourceMappingURL=index.js.map

package/dist/runtime-v2/feature-flags/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/runtime-v2/feature-flags/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,gBAAgB,EAChB,sBAAsB,EACtB,qBAAqB,EACrB,qBAAqB,GACtB,MAAM,4BAA4B,CAAC;AAWpC,OAAO,EACL,mBAAmB,EACnB,oBAAoB,EACpB,uBAAuB,EACvB,uBAAuB,EACvB,kBAAkB,EAClB,qBAAqB,EACrB,iBAAiB,EACjB,wBAAwB,GACzB,MAAM,8BAA8B,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/runtime-v2/feature-flags/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,gBAAgB,EAChB,sBAAsB,EACtB,qBAAqB,EACrB,qBAAqB,GACtB,MAAM,4BAA4B,CAAC;AAWpC,OAAO,EACL,mBAAmB,EACnB,oBAAoB,EACpB,uBAAuB,EACvB,uBAAuB,EACvB,kBAAkB,EAClB,qBAAqB,EACrB,iBAAiB,EACjB,wBAAwB,GACzB,MAAM,8BAA8B,CAAC;AAStC,4DAA4D;AAC5D,OAAO,EACL,iBAAiB,EACjB,mBAAmB,EACnB,sBAAsB,EACtB,gBAAgB,EAChB,SAAS,EACT,YAAY,EACZ,uCAAuC,GACxC,MAAM,2BAA2B,CAAC"}

package/dist/runtime-v2/feature-flags/surface-guard-policy.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Surface Guard Policy — pure logic migrated from openclaw-plugin.
+ *
+ * No I/O, no fs, no network. Operates on PLUGIN_SURFACE_REGISTRY (same
+ * directory) and in-memory module-level Set for once-only log state.
+ *
+ * The guardService<T> generic constraint was relaxed from
+ * <T extends OpenClawPluginService> (a plugin type) to <T> because the
+ * function body only passes the service through — it never accesses
+ * OpenClawPluginService properties. Callers pass concrete service types,
+ * so TypeScript infers T correctly without the constraint.
+ */
+export interface SurfaceGuardResult {
+    passed: boolean;
+    enabledCoreSurfaces: string[];
+    disabledNonCoreSurfaces: string[];
+    violations: string[];
+    warnings: string[];
+}
+type LoggerLike = {
+    info?: (msg: string) => void;
+    debug?: (msg: string) => void;
+};
+/**
+ * Reset the per-process surface-guard skip log bookkeeping. Intended for tests
+ * that need to assert on the first-fire log without cross-test pollution.
+ * Not part of the production API surface; do not call from runtime code.
+ */
+export declare function __resetSurfaceGuardSkipLogStateForTests(): void;
+export declare function checkSurfaceGuard(): SurfaceGuardResult;
+export declare function getSurfaceIdForHook(hookEvent: string, label?: string): string;
+export declare function getSurfaceIdForService(serviceName: string): string;
+export declare function isSurfaceEnabled(surfaceId: string, overrides?: Record<string, boolean>): {
+    enabled: boolean;
+    reason?: string;
+};
+export type HookHandler<E, C, R> = (event: E, ctx: C) => R | Promise<R>;
+export declare function guardHook<E, C, R>(surfaceId: string, logger: LoggerLike | undefined, handler: HookHandler<E, C, R>): HookHandler<E, C, R>;
+export declare function guardService<T>(surfaceId: string, service: T, logger?: LoggerLike): T | null;
+export {};
+//# sourceMappingURL=surface-guard-policy.d.ts.map

package/dist/runtime-v2/feature-flags/surface-guard-policy.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"surface-guard-policy.d.ts","sourceRoot":"","sources":["../../../src/runtime-v2/feature-flags/surface-guard-policy.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAQH,MAAM,WAAW,kBAAkB;IACjC,MAAM,EAAE,OAAO,CAAC;IAChB,mBAAmB,EAAE,MAAM,EAAE,CAAC;IAC9B,uBAAuB,EAAE,MAAM,EAAE,CAAC;IAClC,UAAU,EAAE,MAAM,EAAE,CAAC;IACrB,QAAQ,EAAE,MAAM,EAAE,CAAC;CACpB;AAeD,KAAK,UAAU,GAAG;IAAE,IAAI,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,IAAI,CAAC;IAAC,KAAK,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,IAAI,CAAA;CAAE,CAAC;AAyBlF;;;;GAIG;AACH,wBAAgB,uCAAuC,IAAI,IAAI,CAE9D;AAED,wBAAgB,iBAAiB,IAAI,kBAAkB,CAgCtD;AAED,wBAAgB,mBAAmB,CAAC,SAAS,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM,GAAG,MAAM,CAK7E;AAED,wBAAgB,sBAAsB,CAAC,WAAW,EAAE,MAAM,GAAG,MAAM,CAElE;AAED,wBAAgB,gBAAgB,CAC9B,SAAS,EAAE,MAAM,EACjB,SAAS,GAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAM,GACtC;IAAE,OAAO,EAAE,OAAO,CAAC;IAAC,MAAM,CAAC,EAAE,MAAM,CAAA;CAAE,CA6BvC;AAED,MAAM,MAAM,WAAW,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,IAAI,CAAC,KAAK,EAAE,CAAC,EAAE,GAAG,EAAE,CAAC,KAAK,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC;AAExE,wBAAgB,SAAS,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,EAC/B,SAAS,EAAE,MAAM,EACjB,MAAM,EAAE,UAAU,GAAG,SAAS,EAC9B,OAAO,EAAE,WAAW,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,GAC5B,WAAW,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,CAiBtB;AAED,wBAAgB,YAAY,CAAC,CAAC,EAC5B,SAAS,EAAE,MAAM,EACjB,OAAO,EAAE,CAAC,EACV,MAAM,CAAC,EAAE,UAAU,GAClB,CAAC,GAAG,IAAI,CAYV"}

package/dist/runtime-v2/feature-flags/surface-guard-policy.js

@@ -0,0 +1,143 @@
+/**
+ * Surface Guard Policy — pure logic migrated from openclaw-plugin.
+ *
+ * No I/O, no fs, no network. Operates on PLUGIN_SURFACE_REGISTRY (same
+ * directory) and in-memory module-level Set for once-only log state.
+ *
+ * The guardService<T> generic constraint was relaxed from
+ * <T extends OpenClawPluginService> (a plugin type) to <T> because the
+ * function body only passes the service through — it never accesses
+ * OpenClawPluginService properties. Callers pass concrete service types,
+ * so TypeScript infers T correctly without the constraint.
+ */
+import { PLUGIN_SURFACE_REGISTRY, validateSurfaceRegistry, getSurfacesByCategory, } from './plugin-surface-registry.js';
+// Surface-level once-only log state (PRI-298).
+// The first time a quiet/non-core surface guard actually fires in this
+// process, the disabled reason is emitted once. Subsequent fires for the
+// same surfaceId are still observable (the no-op handler preserves
+// behaviour) but no longer flood the log. Fresh processes start with an
+// empty set, so each plugin load gets one observable skip per surface.
+//
+// The Set is only updated when the log was actually emitted, so passing
+// `undefined` for the logger on a quiet first fire does NOT consume the
+// one-shot slot — a later registration that supplies a logger still gets
+// the first-fire reason (PRI-298 / ERR-002).
+const loggedSkipSurfaces = new Set();
+/**
+ * Emit the disabled-reason log line for `surfaceId` at most once per
+ * process. Returns true if the log was emitted, false if it was suppressed
+ * (already logged, or no logger available). Only marks the surface as
+ * logged when the log was actually written, so a missing logger on first
+ * call does not consume the one-shot slot.
+ */
+function logSkipOnce(surfaceId, logger, message) {
+    if (loggedSkipSurfaces.has(surfaceId)) {
+        return false;
+    }
+    if (!logger?.info) {
+        return false;
+    }
+    loggedSkipSurfaces.add(surfaceId);
+    logger.info(message);
+    return true;
+}
+/**
+ * Reset the per-process surface-guard skip log bookkeeping. Intended for tests
+ * that need to assert on the first-fire log without cross-test pollution.
+ * Not part of the production API surface; do not call from runtime code.
+ */
+export function __resetSurfaceGuardSkipLogStateForTests() {
+    loggedSkipSurfaces.clear();
+}
+export function checkSurfaceGuard() {
+    const validation = validateSurfaceRegistry(PLUGIN_SURFACE_REGISTRY);
+    const violations = [];
+    const warnings = [...validation.warnings];
+    const coreSurfaces = getSurfacesByCategory(PLUGIN_SURFACE_REGISTRY, 'core');
+    const enabledCore = coreSurfaces.filter(s => s.enabledByDefault);
+    const nonCoreEnabled = PLUGIN_SURFACE_REGISTRY.filter(s => s.category !== 'core' && s.enabledByDefault);
+    if (nonCoreEnabled.length > 0) {
+        for (const surface of nonCoreEnabled) {
+            violations.push(`non-core surface '${surface.id}' (${surface.category}) is enabledByDefault=true — must be false per ADR-0014`);
+        }
+    }
+    if (!validation.valid) {
+        violations.push(...validation.errors);
+    }
+    return {
+        passed: violations.length === 0,
+        enabledCoreSurfaces: enabledCore.map(s => s.id),
+        disabledNonCoreSurfaces: PLUGIN_SURFACE_REGISTRY
+            .filter(s => s.category !== 'core' && !s.enabledByDefault)
+            .map(s => s.id),
+        violations,
+        warnings,
+    };
+}
+export function getSurfaceIdForHook(hookEvent, label) {
+    if (label) {
+        return `hook:${hookEvent}.${label}`;
+    }
+    return `hook:${hookEvent}`;
+}
+export function getSurfaceIdForService(serviceName) {
+    return `service:${serviceName}`;
+}
+export function isSurfaceEnabled(surfaceId, overrides = {}) {
+    const entry = PLUGIN_SURFACE_REGISTRY.find(s => s.id === surfaceId);
+    if (!entry) {
+        return {
+            enabled: false,
+            reason: `surface '${surfaceId}' not found in registry — classify before enabling (PRI-289)`,
+        };
+    }
+    if (Object.hasOwn(overrides, surfaceId)) {
+        const override = overrides[surfaceId];
+        if (typeof override !== 'boolean') {
+            return { enabled: entry.enabledByDefault, reason: `override for '${surfaceId}' is not boolean, using default` };
+        }
+        if (entry.category === 'gone') {
+            return { enabled: false, reason: `surface '${surfaceId}' is gone and cannot be re-enabled` };
+        }
+        if (entry.category === 'core' && !override) {
+            return { enabled: true, reason: `surface '${surfaceId}' is core and cannot be disabled` };
+        }
+        return { enabled: override };
+    }
+    if (!entry.enabledByDefault && entry.disabledReason) {
+        return { enabled: false, reason: entry.disabledReason };
+    }
+    return { enabled: entry.enabledByDefault };
+}
+export function guardHook(surfaceId, logger, handler) {
+    const check = isSurfaceEnabled(surfaceId);
+    if (check.enabled) {
+        return handler;
+    }
+    const reason = check.reason ?? 'surface not enabled';
+    // Log on the first ACTUAL no-op invocation, not at construction time
+    // (PRI-298). Construction-time logging would emit a `SKIP` line at
+    // plugin startup for every registered quiet hook, regardless of
+    // whether the hook ever fires — which is exactly the startup log
+    // noise this change is meant to prevent. The one-shot is consumed only
+    // when the log was actually written, so `undefined` logger on first
+    // call does not eat the slot.
+    return (_event, _ctx) => {
+        logSkipOnce(surfaceId, logger, `[PD:surface-guard] SKIP ${surfaceId}: ${reason}`);
+        return undefined;
+    };
+}
+export function guardService(surfaceId, service, logger) {
+    const check = isSurfaceEnabled(surfaceId);
+    if (check.enabled) {
+        return service;
+    }
+    const reason = check.reason ?? 'surface not enabled';
+    // guardService is called once per service during plugin registration,
+    // so the once-only check fires on the registration call itself. The
+    // shared helper makes the consumption rule identical to guardHook:
+    // a missing logger on first call does not consume the one-shot.
+    logSkipOnce(surfaceId, logger, `[PD:surface-guard] SKIP service ${surfaceId}: ${reason}`);
+    return null;
+}
+//# sourceMappingURL=surface-guard-policy.js.map

package/dist/runtime-v2/feature-flags/surface-guard-policy.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"surface-guard-policy.js","sourceRoot":"","sources":["../../../src/runtime-v2/feature-flags/surface-guard-policy.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,EACL,uBAAuB,EACvB,uBAAuB,EACvB,qBAAqB,GACtB,MAAM,8BAA8B,CAAC;AAUtC,+CAA+C;AAC/C,uEAAuE;AACvE,yEAAyE;AACzE,mEAAmE;AACnE,wEAAwE;AACxE,uEAAuE;AACvE,EAAE;AACF,wEAAwE;AACxE,wEAAwE;AACxE,yEAAyE;AACzE,6CAA6C;AAC7C,MAAM,kBAAkB,GAAG,IAAI,GAAG,EAAU,CAAC;AAI7C;;;;;;GAMG;AACH,SAAS,WAAW,CAClB,SAAiB,EACjB,MAA8B,EAC9B,OAAe;IAEf,IAAI,kBAAkB,CAAC,GAAG,CAAC,SAAS,CAAC,EAAE,CAAC;QACtC,OAAO,KAAK,CAAC;IACf,CAAC;IACD,IAAI,CAAC,MAAM,EAAE,IAAI,EAAE,CAAC;QAClB,OAAO,KAAK,CAAC;IACf,CAAC;IACD,kBAAkB,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC;IAClC,MAAM,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;IACrB,OAAO,IAAI,CAAC;AACd,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,uCAAuC;IACrD,kBAAkB,CAAC,KAAK,EAAE,CAAC;AAC7B,CAAC;AAED,MAAM,UAAU,iBAAiB;IAC/B,MAAM,UAAU,GAAG,uBAAuB,CAAC,uBAAuB,CAAC,CAAC;IACpE,MAAM,UAAU,GAAa,EAAE,CAAC;IAChC,MAAM,QAAQ,GAAa,CAAC,GAAG,UAAU,CAAC,QAAQ,CAAC,CAAC;IAEpD,MAAM,YAAY,GAAG,qBAAqB,CAAC,uBAAuB,EAAE,MAAM,CAAC,CAAC;IAC5E,MAAM,WAAW,GAAG,YAAY,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,gBAAgB,CAAC,CAAC;IACjE,MAAM,cAAc,GAAG,uBAAuB,CAAC,MAAM,CACnD,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,QAAQ,KAAK,MAAM,IAAI,CAAC,CAAC,gBAAgB,CACjD,CAAC;IAEF,IAAI,cAAc,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QAC9B,KAAK,MAAM,OAAO,IAAI,cAAc,EAAE,CAAC;YACrC,UAAU,CAAC,IAAI,CACb,qBAAqB,OAAO,CAAC,EAAE,MAAM,OAAO,CAAC,QAAQ,yDAAyD,CAC/G,CAAC;QACJ,CAAC;IACH,CAAC;IAED,IAAI,CAAC,UAAU,CAAC,KAAK,EAAE,CAAC;QACtB,UAAU,CAAC,IAAI,CAAC,GAAG,UAAU,CAAC,MAAM,CAAC,CAAC;IACxC,CAAC;IAED,OAAO;QACL,MAAM,EAAE,UAAU,CAAC,MAAM,KAAK,CAAC;QAC/B,mBAAmB,EAAE,WAAW,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QAC/C,uBAAuB,EAAE,uBAAuB;aAC7C,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,QAAQ,KAAK,MAAM,IAAI,CAAC,CAAC,CAAC,gBAAgB,CAAC;aACzD,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QACjB,UAAU;QACV,QAAQ;KACT,CAAC;AACJ,CAAC;AAED,MAAM,UAAU,mBAAmB,CAAC,SAAiB,EAAE,KAAc;IACnE,IAAI,KAAK,EAAE,CAAC;QACV,OAAO,QAAQ,SAAS,IAAI,KAAK,EAAE,CAAC;IACtC,CAAC;IACD,OAAO,QAAQ,SAAS,EAAE,CAAC;AAC7B,CAAC;AAED,MAAM,UAAU,sBAAsB,CAAC,WAAmB;IACxD,OAAO,WAAW,WAAW,EAAE,CAAC;AAClC,CAAC;AAED,MAAM,UAAU,gBAAgB,CAC9B,SAAiB,EACjB,YAAqC,EAAE;IAEvC,MAAM,KAAK,GAAG,uBAAuB,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,KAAK,SAAS,CAAC,CAAC;IAEpE,IAAI,CAAC,KAAK,EAAE,CAAC;QACX,OAAO;YACL,OAAO,EAAE,KAAK;YACd,MAAM,EAAE,YAAY,SAAS,8DAA8D;SAC5F,CAAC;IACJ,CAAC;IAED,IAAI,MAAM,CAAC,MAAM,CAAC,SAAS,EAAE,SAAS,CAAC,EAAE,CAAC;QACxC,MAAM,QAAQ,GAAG,SAAS,CAAC,SAAS,CAAC,CAAC;QACtC,IAAI,OAAO,QAAQ,KAAK,SAAS,EAAE,CAAC;YAClC,OAAO,EAAE,OAAO,EAAE,KAAK,CAAC,gBAAgB,EAAE,MAAM,EAAE,iBAAiB,SAAS,iCAAiC,EAAE,CAAC;QAClH,CAAC;QACD,IAAI,KAAK,CAAC,QAAQ,KAAK,MAAM,EAAE,CAAC;YAC9B,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,EAAE,YAAY,SAAS,oCAAoC,EAAE,CAAC;QAC/F,CAAC;QACD,IAAI,KAAK,CAAC,QAAQ,KAAK,MAAM,IAAI,CAAC,QAAQ,EAAE,CAAC;YAC3C,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,YAAY,SAAS,kCAAkC,EAAE,CAAC;QAC5F,CAAC;QACD,OAAO,EAAE,OAAO,EAAE,QAAQ,EAAE,CAAC;IAC/B,CAAC;IAED,IAAI,CAAC,KAAK,CAAC,gBAAgB,IAAI,KAAK,CAAC,cAAc,EAAE,CAAC;QACpD,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,EAAE,KAAK,CAAC,cAAc,EAAE,CAAC;IAC1D,CAAC;IAED,OAAO,EAAE,OAAO,EAAE,KAAK,CAAC,gBAAgB,EAAE,CAAC;AAC7C,CAAC;AAID,MAAM,UAAU,SAAS,CACvB,SAAiB,EACjB,MAA8B,EAC9B,OAA6B;IAE7B,MAAM,KAAK,GAAG,gBAAgB,CAAC,SAAS,CAAC,CAAC;IAC1C,IAAI,KAAK,CAAC,OAAO,EAAE,CAAC;QAClB,OAAO,OAAO,CAAC;IACjB,CAAC;IACD,MAAM,MAAM,GAAG,KAAK,CAAC,MAAM,IAAI,qBAAqB,CAAC;IACrD,qEAAqE;IACrE,mEAAmE;IACnE,gEAAgE;IAChE,iEAAiE;IACjE,uEAAuE;IACvE,oEAAoE;IACpE,8BAA8B;IAC9B,OAAO,CAAC,MAAS,EAAE,IAAO,EAAkB,EAAE;QAC5C,WAAW,CAAC,SAAS,EAAE,MAAM,EAAE,2BAA2B,SAAS,KAAK,MAAM,EAAE,CAAC,CAAC;QAClF,OAAO,SAAc,CAAC;IACxB,CAAC,CAAC;AACJ,CAAC;AAED,MAAM,UAAU,YAAY,CAC1B,SAAiB,EACjB,OAAU,EACV,MAAmB;IAEnB,MAAM,KAAK,GAAG,gBAAgB,CAAC,SAAS,CAAC,CAAC;IAC1C,IAAI,KAAK,CAAC,OAAO,EAAE,CAAC;QAClB,OAAO,OAAO,CAAC;IACjB,CAAC;IACD,MAAM,MAAM,GAAG,KAAK,CAAC,MAAM,IAAI,qBAAqB,CAAC;IACrD,sEAAsE;IACtE,oEAAoE;IACpE,mEAAmE;IACnE,gEAAgE;IAChE,WAAW,CAAC,SAAS,EAAE,MAAM,EAAE,mCAAmC,SAAS,KAAK,MAAM,EAAE,CAAC,CAAC;IAC1F,OAAO,IAAI,CAAC;AACd,CAAC"}

package/dist/runtime-v2/index.d.ts

@@ -154,6 +154,8 @@ export { CORE_PRINCIPLES, CORE_PRINCIPLE_IDS, isCorePrincipleId, getCorePrincipl
 export type { CorePrinciple } from './core-principles/index.js';
 export { VALID_SURFACE_KINDS, VALID_MVP_CATEGORIES, PLUGIN_SURFACE_REGISTRY, validateSurfaceRegistry, getEnabledSurfaces, getSurfacesByCategory, getSurfacesByKind, findUnclassifiedSurfaces, } from './feature-flags/index.js';
 export type { SurfaceKind, MvpCategory, PluginSurfaceEntry, SurfaceRegistryValidationResult, } from './feature-flags/index.js';
+export { checkSurfaceGuard, getSurfaceIdForHook, getSurfaceIdForService, isSurfaceEnabled, guardHook, guardService, __resetSurfaceGuardSkipLogStateForTests, } from './feature-flags/index.js';
+export type { SurfaceGuardResult, HookHandler, } from './feature-flags/index.js';
 export { runPromptFixture, runRuleHostFixture, runDeferArchiveFixture, computeProvenChannelStatus, generateContinuityMatrix, recommendProvenChannelNextIssue, isMvpChannel, parseChannels, makePrincipleArtifact, makeRuleArtifact, makeSandboxAlwaysPass, classifyLegacyDependency, MVP_CHANNELS, } from './proven-channel-baseline.js';
 export type { MvpChannel, ChannelFixtureResult, ProvenChannelBaselineSummary, ContinuityMatrixEntry, InputValidationFailure } from './proven-channel-baseline.js';
 export { STORY_A_CHANNELS, makeRunId, makePrincipleArtifactRecord, makeRuleArtifactRecord, computeDemoStatus, buildFollowUpObservation, buildDemoNarrative, validateDemoChannels, createDemoSandboxEvaluate, evaluateDemoGoldenTrace, type DemoNarrativeInput, } from './story-a-demo.js';
@@ -333,4 +335,6 @@ export { SimpleLRU, DetectionFunnelCore } from './detection/index.js';
 export { INTENT_MAX_BYTES, INTENT_DOC_TEMPLATE, INTENT_INJECT_MAX_CHARS, INTENT_TRUNCATION_MARKER, parseIntentDocSections, computeIntentContentHash, validateIntentDocSections, buildIntentFrictionBlock, NullIntentDocReader, generateIntentPatchProposal, } from './intent/index.js';
 export type { IntentDocSections, IntentDocWarning, IntentDocWarningCode, IntentFrictionBlockInput, IntentDocReader, IntentDocReadResult, IntentDocReference, IntentDocReadReason, IntentDecisionRecord, IntentDecisionInput, IntentDecisionRecordResult, IntentDecisionSummary, IntentDecisionStore, FollowUpPatch, IntentPatchProposal, } from './intent/index.js';
 export { SqliteIntentDecisionStore } from './store/intent/index.js';
+export type { FileModification } from './risk/index.js';
+export { estimateLineChanges } from './risk/index.js';
 //# sourceMappingURL=index.d.ts.map