@pareto4/pp-core 1.12.1 → 1.17.1

package/pp-core/bin/lib/capability-state.cjs

@@ -62,6 +62,137 @@ function _isSafePropKey(key) {
         return false;
     return true;
 }
+// ─── Vault mode filter (Phase 15 D-02 / D-28) ──────────────────────────────────
+/**
+ * Does a hook's declared `vaultMode` filter let it through under the resolved
+ * mode? THE ONE statement of the rule (Phase 15 D-02, amended by D-28). Both
+ * `resolveLoopHooks` (what renders) and `resolveCapabilityState` (what
+ * `capability state` reports) call it, so they cannot drift. It lives here, not
+ * in loop-resolver, because loop-resolver already requires this module and the
+ * reverse require would be a cycle.
+ *
+ *   - no `vaultMode` on the hook → passes (a hook without the field behaves
+ *     exactly as before Phase 15);
+ *   - the input mode is `practices` or `standards` → passes iff the hook's
+ *     `vaultMode` equals it;
+ *   - any other input (`null`, absent, an unknown string) is an undefined mode:
+ *     a filtered GATE passes and a filtered contribution or step drops (D-28).
+ *     The trace points then still dispatch a gate that fails closed, and no
+ *     contract renders for a mode nobody defined. The mode is never defaulted
+ *     to `practices` here.
+ *
+ * Pure: no I/O, no config read. The mode arrives as a value.
+ */
+function vaultModeFilterVerdict(hookMode, kind, inputMode) {
+    if (hookMode === undefined)
+        return true;
+    const resolved = (inputMode === 'practices' || inputMode === 'standards') ? inputMode : null;
+    if (resolved !== null)
+        return hookMode === resolved;
+    return kind === 'gate';
+}
+/**
+ * Call an injected `resolveVaultMode` (pp-tools builds it on `vaultModeVerdict`)
+ * and normalise its answer to `'practices' | 'standards' | null`. A missing
+ * resolver, a throw or any other answer is `null`, the undefined mode that
+ * `vaultModeFilterVerdict` treats fail-closed (D-28). Shared by both I/O entry
+ * points (`cmdLoopRenderHooks`, `cmdCapabilityState`) so the two read the
+ * injected mode identically.
+ */
+function resolveInjectedVaultMode(resolveVaultMode) {
+    try {
+        const m = typeof resolveVaultMode === 'function' ? resolveVaultMode() : null;
+        return (m === 'practices' || m === 'standards') ? m : null;
+    }
+    catch {
+        return null;
+    }
+}
+// ─── Seal gates over recorded artifacts (Phase 16 D-18 / D-19 / D-26) ──────────
+/**
+ * The per-hook seal field's name (Phase 16 D-19). One statement of it: the
+ * resolver reads the hook field under this name and the registry generator
+ * validates the same name, so the two cannot name different fields.
+ */
+const SEAL_FIELD = 'onRecordedArtifacts';
+/**
+ * How the resolver treats one GATE, given its seal field, its capability's
+ * state and the injected recorded-artifacts predicate. THE ONE statement of
+ * the seal rule (Phase 16 D-19), owned here for the same reason as
+ * `vaultModeFilterVerdict`: loop-resolver requires this module, never the
+ * reverse.
+ *
+ * Why a field and not a widened `when` (D-18, measured): the resolver drops a
+ * hook whose capability is not `active` BEFORE `when` is read, and `active`
+ * ANDs the capability's `activationKey`. With `vault.enabled` or
+ * `vault.practices_enabled` false no vault-practices hook can render, whatever
+ * its `when` says. So a seal gate bypasses the active check and the `when`,
+ * under this closed rule only:
+ *
+ *   - no seal field (anything but literal `true`) → `'normal'` when the
+ *     capability is active, else `'drop'`. That is the resolver's behaviour
+ *     before Phase 16, exactly; `when` is then evaluated as before.
+ *   - a seal gate whose capability is active → `'drop'`: the normal gates
+ *     cover it, so a check is never dispatched twice.
+ *   - a seal gate whose capability is not `enabled` (not installed or not
+ *     surfaced), or has no state at all → `'drop'` (fail closed).
+ *   - otherwise (enabled, config-inactive) → `'seal'` iff the predicate
+ *     answers literal `true`, else `'drop'`. The predicate is called on this
+ *     arm ONLY, so no other hook pays its planning-tree read.
+ *
+ * Mode filtering (`vaultModeFilterVerdict`) runs BEFORE this rule in the
+ * resolver, so a mode-filtered seal never consults the predicate (research
+ * C-1). Seals are declared on vault-practices only (D-26). Pure apart from the
+ * injected thunk.
+ */
+function sealRenderVerdict(sealField, state, recordedArtifacts) {
+    const active = state !== undefined && state !== null && state.active === true;
+    if (sealField !== true)
+        return active ? 'normal' : 'drop';
+    if (active)
+        return 'drop';
+    if (state === undefined || state === null || state.enabled !== true)
+        return 'drop';
+    return recordedArtifacts() === true ? 'seal' : 'drop';
+}
+/**
+ * Call an injected `resolveRecordedArtifacts` (pp-tools builds it on the seal
+ * leaf's `hasRecordedVaultArtifacts`) and normalise its answer to a boolean:
+ * literal `true` is `true`; a missing resolver, a throw or any other answer
+ * (`'true'`, `1`, `undefined`) is `false`, the inert value under which no seal
+ * renders (Phase 16 D-19). The leaf itself answers `true` when it cannot prove
+ * absence (D-44); this normaliser only refuses answers that are not a boolean.
+ */
+function resolveInjectedRecordedArtifacts(resolveRecordedArtifacts) {
+    try {
+        if (typeof resolveRecordedArtifacts !== 'function')
+            return false;
+        return resolveRecordedArtifacts() === true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Quick 261015-ect (QD-13): call an injected `resolvePlatformBindingsPresent`
+ * (pp-tools builds it on the vault leaf's `hasPlatformBindings`) and normalise
+ * its answer: literal `false` is `false` (measured absent), literal `true` is
+ * `true`; a missing resolver, a throw or any other answer is `null`, "could not
+ * measure". The resolver drops a bindings-requiring capability's hooks only on
+ * `false`: a filter that cannot measure must never silence a gate on a governed
+ * project, so the unmeasured answer renders as before.
+ */
+function resolveInjectedPlatformBindingsPresent(resolvePlatformBindingsPresent) {
+    try {
+        if (typeof resolvePlatformBindingsPresent !== 'function')
+            return null;
+        const answer = resolvePlatformBindingsPresent();
+        return answer === true || answer === false ? answer : null;
+    }
+    catch {
+        return null;
+    }
+}
 // ─── Pure resolver ─────────────────────────────────────────────────────────────
 /**
  * Deterministic resolver: for each capability in the registry, produce the
@@ -85,9 +216,12 @@ function _isSafePropKey(key) {
  * @param input.cwd              Optional; when provided, enables raw .planning/config.json
  *                               fallback reads (levels 2+3 of _resolveActivationValue
  *                               precedence). Omit for a pure in-memory resolution.
+ * @param input.vaultMode        Optional resolved vault mode VALUE; a hook carrying
+ *                               `vaultMode` is configured only when
+ *                               `vaultModeFilterVerdict` passes it (Phase 15 D-02/D-28).
  */
 function resolveCapabilityState(input) {
-    const { registry, installedSkills, surfacedSkills, config, cwd } = input;
+    const { registry, installedSkills, surfacedSkills, config, cwd, vaultMode } = input;
     // Guard: registry missing capabilities
     if (!registry || typeof registry !== 'object' || Array.isArray(registry)) {
         return { capabilities: [] };
@@ -217,6 +351,10 @@ function resolveCapabilityState(input) {
                     // (mirrors loop-resolver.isActive: `typeof when !== 'string' || when.length === 0` → false)
                     configured = false;
                 }
+                // Phase 15 D-02/D-28: the mode filter folds into `configured`, through the
+                // same rule resolveLoopHooks applies. `vaultMode` is read, never emitted:
+                // HookEntry has no such field.
+                configured = configured && vaultModeFilterVerdict(h['vaultMode'], kind, vaultMode);
                 // Hook active = capability-level active AND hook's own config gate.
                 // The capability's `active` constant (= enabled && configActivation) is
                 // used here so that a config-disabled capability (active=false) cannot
@@ -381,8 +519,12 @@ function _resolveManifest(commandsGsdDir, configDir) {
  *                         caught by the caller before invoking this function.
  * @param raw              Whether to emit raw JSON (io.output raw mode)
  * @param _options         Reserved for future use
+ * @param resolveOptions   `{ vaultMode }`, the resolved vault mode VALUE passed
+ *                         through to resolveCapabilityState (Phase 15 D-02).
+ *                         Omitted by the loop resolver, which reads only the
+ *                         capability-level `active` and filters hooks itself.
  */
-function resolveCapabilityRuntimeState(cwd, runtimeConfigDir, configOverride) {
+function resolveCapabilityRuntimeState(cwd, runtimeConfigDir, configOverride, resolveOptions = {}) {
     const warnings = [];
     // Resolve runtimeConfigDir using the canonical runtime-homes resolver.
     // When not provided, the active runtime is detected via the canonical
@@ -488,6 +630,7 @@ function resolveCapabilityRuntimeState(cwd, runtimeConfigDir, configOverride) {
         surfacedSkills,
         config,
         cwd,
+        vaultMode: resolveOptions.vaultMode,
     });
     return {
         runtimeConfigDir: resolvedConfigDir,
@@ -495,8 +638,11 @@ function resolveCapabilityRuntimeState(cwd, runtimeConfigDir, configOverride) {
         capabilities: result.capabilities,
     };
 }
-function cmdCapabilityState(cwd, runtimeConfigDir, raw, _options = {}) {
-    const result = resolveCapabilityRuntimeState(cwd, runtimeConfigDir);
+function cmdCapabilityState(cwd, runtimeConfigDir, raw, options = {}) {
+    // Phase 15 D-02: the same injected mode render-hooks uses, so a mode-filtered
+    // hook's `active` here agrees with whether it renders.
+    const vaultMode = resolveInjectedVaultMode(options['resolveVaultMode']);
+    const result = resolveCapabilityRuntimeState(cwd, runtimeConfigDir, undefined, { vaultMode });
     for (const warning of result.warnings) {
         coreError(`capability state: ${warning}`);
     }
@@ -533,6 +679,16 @@ module.exports = {
     resolveCapabilityRuntimeState,
     isCapabilityActive,
     cmdCapabilityState,
+    // Phase 15 D-02/D-28: the one mode-filter rule (loop-resolver imports it)
+    vaultModeFilterVerdict,
+    resolveInjectedVaultMode,
+    // Phase 16 D-19: the one seal rule, its injected-predicate normaliser and the
+    // field name the resolver and the registry generator both read.
+    SEAL_FIELD,
+    sealRenderVerdict,
+    resolveInjectedRecordedArtifacts,
+    // Quick 261015-ect (QD-13): the bindings measurement's normaliser.
+    resolveInjectedPlatformBindingsPresent,
     // Exported for tests
     _resolveCommandsGsdDir,
     _loadInstalledSkillsManifest,

package/pp-core/bin/lib/capability-writer.cjs

@@ -28,6 +28,8 @@ const { output: coreOutput, error: coreError } = ioMod;
 // eslint-disable-next-line @typescript-eslint/no-require-imports
 const capabilityStateMod = require("./capability-state.cjs");
 const { resolveCapabilityRuntimeState, _resolveManifest, _resolveCommandsGsdDir } = capabilityStateMod;
+// On its own line: the line above is baselined verbatim by scripts/verify-rename-guard.cjs.
+const { resolveInjectedVaultMode } = capabilityStateMod;
 // eslint-disable-next-line @typescript-eslint/no-require-imports
 const surfaceMod = require("./surface.cjs");
 const { readSurface, writeSurface, applySurface } = surfaceMod;
@@ -67,8 +69,15 @@ const nodepath = require("path");
 function setCapabilityState(cwd, runtimeConfigDir, desired, opts) {
     const warnings = [];
     const errors = [];
+    // Phase 15 D-02 / 15-REVIEW WR-07: the mode every hook-level reader uses, so
+    // the hooks this command reports and warns about are the hooks that render.
+    // 15-REVIEW iter-2 WR-01: the mode is resolved PER READ, never once per
+    // command — `vaultModeVerdict` answers "no mode" while `vault.enabled` is off,
+    // so a command that itself turns the vault on must re-ask after its write.
     // ── Step 1: Resolve BEFORE state once ────────────────────────────────────
-    const before = resolveCapabilityRuntimeState(cwd, runtimeConfigDir);
+    const before = resolveCapabilityRuntimeState(cwd, runtimeConfigDir, undefined, {
+        vaultMode: resolveInjectedVaultMode(opts?.resolveVaultMode),
+    });
     const resolvedConfigDir = before.runtimeConfigDir;
     // ── Load registry ─────────────────────────────────────────────────────────
     // eslint-disable-next-line @typescript-eslint/no-require-imports
@@ -255,7 +264,11 @@ function setCapabilityState(cwd, runtimeConfigDir, desired, opts) {
         }
     }
     // ── Step 5: RE-RESOLVE ────────────────────────────────────────────────────
-    const after = resolveCapabilityRuntimeState(cwd, resolvedConfigDir);
+    // Re-resolve the mode AFTER the writes above (iter-2 WR-01): the after-state
+    // must be judged under the mode `capability state` / render-hooks now see.
+    const after = resolveCapabilityRuntimeState(cwd, resolvedConfigDir, undefined, {
+        vaultMode: resolveInjectedVaultMode(opts?.resolveVaultMode),
+    });
     // ── Step 6: POST CHECKS ───────────────────────────────────────────────────
     // Check: desired enabled=true but not actually enabled after write
     // (catches the not-in-profile / not-surfaced silent no-op case).
@@ -313,9 +326,10 @@ function cmdCapabilitySet(cwd, runtimeConfigDir, capId, options, raw) {
             ...(options.gates ? { gates: options.gates } : {}),
         },
     ];
-    const opts = options.runtime
-        ? { materialize: { runtime: options.runtime, scope: options.scope ?? 'global' } }
-        : undefined;
+    const opts = {
+        ...(options.runtime ? { materialize: { runtime: options.runtime, scope: options.scope ?? 'global' } } : {}),
+        resolveVaultMode: options.resolveVaultMode,
+    };
     const result = setCapabilityState(cwd, runtimeConfigDir, desired, opts);
     if (raw) {
         // Raw mode: emit JSON to stdout including errors; exit non-zero if errors present.