@pareto4/pp-core 1.13.0 → 1.18.0

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

@@ -62,6 +62,86 @@ function _isSafePropKey(key) {
         return false;
     return true;
 }
+// ─── 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 because 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` false no vault
+ * 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.
+ *
+ * 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
@@ -222,7 +302,12 @@ function resolveCapabilityState(input) {
                 // used here so that a config-disabled capability (active=false) cannot
                 // produce active hooks even when the hook's own `when` is unconditional
                 // (configured=true). The capability gate cascades to all its hooks.
-                hooks.push({ point, kind, when: whenRaw, configured, active: active && configured });
+                // A seal gate (`SEAL_FIELD`, Phase 16 D-19) never renders for an ACTIVE
+                // capability — `sealRenderVerdict` drops it, because the normal gates
+                // cover it — so it is reported inactive here, keeping this report in
+                // agreement with what `loop render-hooks` renders.
+                const seal = kind === 'gate' && h[SEAL_FIELD] === true;
+                hooks.push({ point, kind, when: whenRaw, configured, active: active && configured && !seal });
             }
         }
         const stepsRaw = capObj['steps'];
@@ -533,6 +618,13 @@ module.exports = {
     resolveCapabilityRuntimeState,
     isCapabilityActive,
     cmdCapabilityState,
+    // 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

@@ -313,9 +313,9 @@ 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' } } : {}),
+    };
     const result = setCapabilityState(cwd, runtimeConfigDir, desired, opts);
     if (raw) {
         // Raw mode: emit JSON to stdout including errors; exit non-zero if errors present.