@pareto4/pp-core 1.13.0 → 1.17.1

package/pp-core/bin/lib/loop-resolver.cjs

@@ -13,7 +13,7 @@
  * Command surface: pp-tools loop render-hooks <point>
  *
  * Exports (three things):
- *   resolveLoopHooks({ point, registry, config }) → { point, activeHooks }
+ *   resolveLoopHooks({ point, registry, config, vaultMode?, recordedArtifacts? }) → { point, activeHooks }
  *   renderLoopHooks(resolved) → markdown string
  *   cmdLoopRenderHooks(cwd, point, raw, options) — I/O entry point
  *
@@ -30,19 +30,17 @@
  */
 // eslint-disable-next-line @typescript-eslint/no-require-imports
 const ioMod = require("./io.cjs");
-const { output: coreOutput, error: coreError, ERROR_REASON } = ioMod;
+const { output: coreOutput, error: coreError } = ioMod;
 // eslint-disable-next-line @typescript-eslint/no-require-imports
 const configLoaderModule = require("./config-loader.cjs");
-const { loadConfig, unreadableConfigFiles, describeUnreadableConfig } = configLoaderModule;
+const { loadConfig } = configLoaderModule;
 // eslint-disable-next-line @typescript-eslint/no-require-imports
 const capabilityStateModule = require("./capability-state.cjs");
-const { resolveCapabilityRuntimeState } = capabilityStateModule;
+const { resolveCapabilityRuntimeState, vaultModeFilterVerdict, resolveInjectedVaultMode, SEAL_FIELD, sealRenderVerdict, resolveInjectedRecordedArtifacts, resolveInjectedPlatformBindingsPresent, } = capabilityStateModule;
 // ─── Capability-activation engine (single owner for config-key precedence) ────
 // eslint-disable-next-line @typescript-eslint/no-require-imports
 const capabilityActivationModule = require("./capability-activation.cjs");
 const { _getNestedConfigValue, _readRawConfigKey, _resolveActivationValue, resolveConfigKey } = capabilityActivationModule;
-// ─── Phase ceremony tier (pack 9): `--phase` / `--tier` overlay ───────────────
-const phase_tier_cjs_1 = require("./phase-tier.cjs");
 // ─── Canonical points (derived from LOOP_HOST_CONTRACT — authoritative 12) ───
 // FIX 2: Derive the authoritative canonical set from LOOP_HOST_CONTRACT so it
 // cannot drift from the host contract. CANONICAL_POINTS_FALLBACK is kept as an
@@ -105,7 +103,7 @@ function _getCanonicalPoints(_registry) {
  * resolved against `config`; active iff truthy. Inactive hooks are filtered out.
  */
 function resolveLoopHooks(input) {
-    const { point, registry, config, cwd, capabilityStatesById } = input;
+    const { point, registry, config, cwd, capabilityStatesById, vaultMode, recordedArtifacts, platformBindingsPresent, } = input;
     // Validate point
     const canonicalPoints = _getCanonicalPoints(registry);
     if (!canonicalPoints.includes(point)) {
@@ -124,6 +122,12 @@ function resolveLoopHooks(input) {
     }
     const entryMap = entry;
     const activeHooks = [];
+    // Phase 15 D-02/D-28: the per-hook `vaultMode` filter, one rule owned by
+    // capability-state (`vaultModeFilterVerdict`), evaluated against the injected
+    // mode VALUE. The field is read here and never copied into an ActiveHook.
+    function modeOk(hook, kind) {
+        return vaultModeFilterVerdict(hook['vaultMode'], kind, vaultMode);
+    }
     // Helper: check activation using single-key precedence resolver (FIX 1 + FIX 3)
     function isActive(hook) {
         const when = hook['when'];
@@ -150,6 +154,59 @@ function resolveLoopHooks(input) {
         // `=== true` is the correct fail-closed check (not `!== false`).
         return state.active === true;
     }
+    // Phase 16 D-19: the state the seal rule reads for a gate's capability. With
+    // no state map at all, every capability is treated as active, exactly as
+    // `isCapabilityActive` does: normal gates keep today's behaviour and a seal
+    // gate drops (it never renders while its capability is active). With a map,
+    // a missing entry is `undefined`, which the rule drops (fail closed).
+    function gateStateOf(capId) {
+        if (!capabilityStatesById)
+            return { enabled: true, active: true };
+        return capabilityStatesById instanceof Map
+            ? capabilityStatesById.get(capId)
+            : capabilityStatesById[capId];
+    }
+    // Phase 16 D-19 / T-16-33: the injected predicate is asked at most once per
+    // resolve, however many seal gates the point declares. An absent thunk is
+    // the inert answer (no seal renders).
+    let recordedArtifactsMemo;
+    function recordedArtifactsOnce() {
+        if (recordedArtifactsMemo === undefined) {
+            recordedArtifactsMemo = resolveInjectedRecordedArtifacts(recordedArtifacts);
+        }
+        return recordedArtifactsMemo;
+    }
+    // Quick 261015-ect (QD-13): the bindings measurement, asked at most once per
+    // resolve and only for a capability that declares it needs the file. A
+    // missing thunk is `null` (unmeasured), which drops nothing.
+    let bindingsPresentMemo;
+    function bindingsPresentOnce() {
+        if (bindingsPresentMemo === undefined) {
+            bindingsPresentMemo = resolveInjectedPlatformBindingsPresent(platformBindingsPresent);
+        }
+        return bindingsPresentMemo;
+    }
+    function requiresBindings(capId) {
+        // Prototype-pollution guard (inline literal, CodeQL barrier), as the
+        // registry generator guards capability ids.
+        if (capId === '' || capId === '__proto__' || capId === 'constructor' || capId === 'prototype')
+            return false;
+        const caps = registry['capabilities'];
+        if (!caps || typeof caps !== 'object' || Array.isArray(caps))
+            return false;
+        if (!Object.prototype.hasOwnProperty.call(caps, capId))
+            return false;
+        const cap = caps[capId];
+        if (!cap || typeof cap !== 'object')
+            return false;
+        return cap['requiresPlatformBindings'] === true;
+    }
+    // A capability that requires bindings renders nothing where the file is
+    // MEASURED absent: the project is not governed by it (its own description says
+    // it is inert unless the bindings exist).
+    function droppedForBindings(capId) {
+        return requiresBindings(capId) && bindingsPresentOnce() === false;
+    }
     // Helper: safe string array
     function toStringArray(v) {
         if (!Array.isArray(v))
@@ -201,6 +258,10 @@ function resolveLoopHooks(input) {
         const capId = typeof hook['capId'] === 'string' ? hook['capId'] : '';
         if (!isCapabilityActive(capId))
             continue;
+        if (droppedForBindings(capId))
+            continue;
+        if (!modeOk(hook, 'step'))
+            continue;
         if (!isActive(hook))
             continue;
         const ref = (typeof hook['ref'] === 'object' && hook['ref'] !== null)
@@ -235,6 +296,10 @@ function resolveLoopHooks(input) {
         const capId = typeof hook['capId'] === 'string' ? hook['capId'] : '';
         if (!isCapabilityActive(capId))
             continue;
+        if (droppedForBindings(capId))
+            continue;
+        if (!modeOk(hook, 'contribution'))
+            continue;
         if (!isActive(hook))
             continue;
         const into = typeof hook['into'] === 'string' ? hook['into'] : undefined;
@@ -268,9 +333,24 @@ function resolveLoopHooks(input) {
         if (!hook || typeof hook !== 'object')
             continue;
         const capId = typeof hook['capId'] === 'string' ? hook['capId'] : '';
-        if (!isCapabilityActive(capId))
+        // Quick 261015-ect (QD-13): gates too, seal gates included. A project with
+        // no bindings holds no engine-written vault records (D-37/D-42), and every
+        // vault gate already answers inert there, so nothing is left ungated.
+        if (droppedForBindings(capId))
             continue;
-        if (!isActive(hook))
+        // Phase 16 D-19 / research C-1: the mode filter runs FIRST, so a
+        // mode-filtered seal gate never consults the recorded-artifacts predicate
+        // (a default standards project pays no planning-tree read for a seal it
+        // cannot render). `modeOk` is pure, so the order changes no other result.
+        if (!modeOk(hook, 'gate'))
+            continue;
+        const verdict = sealRenderVerdict(hook[SEAL_FIELD], gateStateOf(capId), recordedArtifactsOnce);
+        if (verdict === 'drop')
+            continue;
+        // 'normal': today's path, `when` evaluated. 'seal': the `when` IS the
+        // switch that is off (D-18), so it is not read; the seal rule already
+        // required an enabled, config-inactive capability and recorded artifacts.
+        if (verdict === 'normal' && !isActive(hook))
             continue;
         const when = typeof hook['when'] === 'string' ? hook['when'] : undefined;
         const check = hook['check'] !== undefined ? hook['check'] : undefined;
@@ -382,80 +462,6 @@ function renderLoopHooks(resolved) {
     return lines.join('\n');
 }
 // ─── I/O command handler ───────────────────────────────────────────────────────
-/**
- * The refusal text for a caller that resolves hooks over an unreadable config.
- * One wording for every such caller (`loop render-hooks`, `phase.dispatch-plan`).
- */
-function unreadableConfigRefusal(what, unreadable) {
-    return (`${what} refused: the project config cannot be read, so no hook can be resolved ` +
-        `(rendering anyway would silently drop every hook the config switches on, a required client vault among them). ` +
-        `${describeUnreadableConfig(unreadable)}. Repair or remove the file, then re-run. Stop this workflow here.`);
-}
-/**
- * Resolve the active hooks at `point` for the project at `cwd`, exactly as
- * `loop render-hooks` does: refuse an unreadable config, load the config
- * snapshot once, overlay the phase tier's gate booleans when one is given,
- * resolve capability state over the same snapshot, then resolve the hooks.
- * The ONE owner of "which hooks are active here" for every caller that needs
- * the answer in code (`loop render-hooks`, `phase.dispatch-plan`'s executor
- * contributions). Never exits; the caller decides how to report a refusal.
- */
-function resolveProjectLoopHooks(cwd, point, opts = {}) {
-    // Fail closed on a config that exists but cannot be read. Every hook's `when`
-    // and activation key is read from it, and both readers below swallow a parse
-    // failure into the defaults, so rendering anyway drops exactly the hooks the
-    // project switched on — a required client vault's fetch and blocking gate
-    // among them. A MISSING config is not refused: that is a fresh project, and
-    // the defaults are its real settings.
-    const unreadable = unreadableConfigFiles(cwd);
-    if (unreadable.length > 0) {
-        return { ok: false, reason: 'config_unreadable', message: unreadableConfigRefusal(opts.what ?? `loop render-hooks ${point}`, unreadable) };
-    }
-    // Load the config snapshot ONCE and share it with both the capability-state
-    // resolver (via configOverride) and loop-hook resolution, so federated keys
-    // present in loadConfig resolve identically for `active` and for hook when/
-    // configValues. Keys absent from loadConfig still fall through to raw
-    // .planning/config.json reads (precedence levels 2-3) in each pass.
-    let config;
-    try {
-        config = loadConfig(cwd);
-    }
-    catch {
-        config = {};
-    }
-    if (opts.phaseTier)
-        config = (0, phase_tier_cjs_1.overlayTierGates)(config, opts.phaseTier);
-    const state = resolveCapabilityRuntimeState(cwd, opts.configDir, config);
-    // Registry is the static generated module — same object capability-state uses internally.
-    // eslint-disable-next-line @typescript-eslint/no-require-imports
-    const registry = require('./capability-registry.cjs');
-    const capabilityStatesById = new Map();
-    for (const cap of state.capabilities || []) {
-        capabilityStatesById.set(cap.id, cap);
-    }
-    try {
-        const resolved = resolveLoopHooks({ point, registry, config, cwd, capabilityStatesById });
-        return { ok: true, resolved, warnings: state.warnings ?? [] };
-    }
-    catch (err) {
-        return { ok: false, reason: 'invalid_point', message: (err instanceof Error) ? err.message : String(err) };
-    }
-}
-/**
- * The `fragment.inline` text of every active contribution into `role`, in
- * resolved order, with the capability that contributed it.
- */
-function contributionsInto(resolved, role) {
-    const out = [];
-    for (const h of resolved.activeHooks) {
-        if (h.kind !== 'contribution' || h.into !== role)
-            continue;
-        if (typeof h.fragment?.inline !== 'string')
-            continue;
-        out.push({ capId: h.capId, fragment: h.fragment.inline });
-    }
-    return out;
-}
 /**
  * Command entry point: load registry + config, resolve + render, emit envelope.
  *
@@ -470,31 +476,39 @@ function contributionsInto(resolved, role) {
  * pre-cutover keys like `workflow.ui_phase` that live in config.json but are not
  * yet exposed through loadConfig's whitelist.
  *
- * Unreadable config: when any project config file exists but cannot be parsed
- * (`unreadableConfigFiles`), every mode refuses before rendering — exit 1,
- * empty stdout, one stderr line naming each file and its parse error.
- *
- * --active-cap <capId>: when present, resolves hooks for <point> exactly as the
- * normal path does, then prints exactly `true` (if any resolved activeHook has
- * capId === <capId>) or `false` followed by a single newline, and exits 0.
+ * --active-cap <capId>: when present, resolves hooks for <point> as the normal
+ * path does EXCEPT for one input — the bindings measurement (quick 261015-ect,
+ * QD-13) is not applied — then prints exactly `true` (if any resolved
+ * activeHook has capId === <capId>) or `false` followed by a single newline,
+ * and exits 0. So on a project with no `.platform-bindings.json` it still
+ * answers the config switch alone: /pp-init Step 2.6's unbound arm ("a
+ * resolving profile with no bindings halts loudly") is reachable only because
+ * this read ignores bindings (16-16 D-81), and the D-28 parity test states
+ * parity on bindings-present shapes only.
  * No JSON envelope is emitted — output is clean for shell $(…) capture.
  * Missing <capId> value → coreError + non-zero exit.
  * Unknown/inactive capId → `false` (not an error).
  *
- * --into <role>: resolves exactly as the normal path does, then prints the
- * `fragment.inline` text of each active contribution whose `into` equals
- * <role>, in resolved order, separated by one blank line, with a trailing
- * newline when anything printed. Nothing at all (empty stdout, exit 0) when no
- * contribution matches. No JSON envelope; `--raw` is ignored. `--active-cap`
- * takes precedence: given both, `--into` is ignored.
+ * --into <role> (Phase 15 D-12/D-30): resolves exactly as the normal path does,
+ * then prints the `fragment.inline` text of each active contribution whose
+ * `into` equals <role>, in resolved order, separated by one blank line, with a
+ * trailing newline when anything printed. Nothing at all (empty stdout, exit
+ * 0) when no contribution matches. No JSON envelope; `--raw` is ignored. This
+ * is the text execute-phase interpolates verbatim into a spawn prompt (15-09).
+ * `--active-cap` takes precedence: given both, `--into` is ignored.
  *
- * --phase <N> [--tier light|standard|heavy] (pack 9): resolve the phase's
- * ceremony tier (src/phase-tier.cts) and overlay its gate booleans
- * (`workflow.research`, `workflow.pattern_mapper`, …) on the config snapshot
- * BEFORE capability state and hook activation read it, so every `when` /
- * activation key of those gates answers the tier-resolved value. Without
- * `--phase` the project's own booleans are read as before (an explicitly
- * invoked gate command such as /pp-secure-phase is not governed by a tier).
+ * options.resolveVaultMode: an injected `() => mode | null` (pp-tools builds it
+ * on vaultModeVerdict). This module never imports vault code (D-02).
+ *
+ * options.resolveRecordedArtifacts: an injected `() => boolean` (pp-tools builds
+ * it on the seal leaf's hasRecordedVaultArtifacts); only literal `true` lets a
+ * seal gate render (Phase 16 D-19). `--active-cap <cap>` also requires the
+ * capability's own state to be active (D-27).
+ *
+ * options.resolvePlatformBindingsPresent: an injected `() => boolean` (pp-tools
+ * builds it on the vault leaf's hasPlatformBindings); only literal `false`
+ * drops a `requiresPlatformBindings` capability's hooks (QD-13). `--into` and
+ * the envelope read the filtered set; `--active-cap` reads the unfiltered one.
  */
 function cmdLoopRenderHooks(cwd, point, raw, options = {}) {
     if (!point) {
@@ -509,40 +523,85 @@ function cmdLoopRenderHooks(cwd, point, raw, options = {}) {
     }
     // --into <role> mode: emit matching contribution fragment text only
     const intoRole = typeof options['into'] === 'string' ? options['into'] : undefined;
-    if (activeCapId === undefined && intoRole !== undefined && intoRole.trim() === '') {
-        coreError('Missing value for --into (e.g. --into executor)', ERROR_REASON.USAGE);
+    if (activeCapId === undefined && intoRole !== undefined && intoRole === '') {
+        coreError('--into requires a <role> value (e.g. --into executor)');
         return;
     }
     const runtimeConfigDir = typeof options['configDir'] === 'string'
         ? options['configDir']
         : undefined;
-    const tierPhase = typeof options['phase'] === 'string' && options['phase'] !== '' ? options['phase'] : null;
-    const tierCli = typeof options['tier'] === 'string' && options['tier'] !== '' ? options['tier'] : null;
-    let phaseTier = null;
-    if (tierPhase !== null || tierCli !== null) {
-        if (tierCli !== null && !['light', 'standard', 'heavy'].includes(tierCli)) {
-            coreError('--tier needs one of light, standard, heavy');
-            return;
-        }
-        // The refusal below must come first: never resolve a tier from a config it cannot read.
-        if (unreadableConfigFiles(cwd).length === 0)
-            phaseTier = (0, phase_tier_cjs_1.resolvePhaseTierForProject)(cwd, tierPhase, tierCli);
+    // Load the config snapshot ONCE and share it with both the capability-state
+    // resolver (via configOverride) and loop-hook resolution, so federated keys
+    // present in loadConfig resolve identically for `active` and for hook when/
+    // configValues — eliminating the previous double loadConfig() call. Note: keys
+    // absent from loadConfig still fall through to raw .planning/config.json reads
+    // (precedence levels 2-3) in each pass; that residual re-read window is
+    // pre-existing (unchanged by this consolidation), not introduced here.
+    let config;
+    try {
+        config = loadConfig(cwd);
     }
-    const outcome = resolveProjectLoopHooks(cwd, point, { configDir: runtimeConfigDir, phaseTier });
-    if (!outcome.ok) {
-        coreError(outcome.message, outcome.reason === 'config_unreadable' ? ERROR_REASON.CONFIG_PARSE_FAILED : undefined);
+    catch {
+        config = {};
+    }
+    const state = resolveCapabilityRuntimeState(cwd, runtimeConfigDir, config);
+    // Registry is the static generated module — same object capability-state uses internally.
+    // eslint-disable-next-line @typescript-eslint/no-require-imports
+    const registry = require('./capability-registry.cjs');
+    const capabilityStatesById = new Map();
+    for (const cap of state.capabilities || []) {
+        capabilityStatesById.set(cap.id, cap);
+    }
+    // Phase 15 D-02: the vault mode arrives through an injected resolver (pp-tools
+    // passes one built on vaultModeVerdict). A missing resolver, a throw or a
+    // non-mode answer is `null`, the fail-closed undefined mode (D-28).
+    const vaultMode = resolveInjectedVaultMode(options['resolveVaultMode']);
+    // Phase 16 D-19: the recorded-artifacts predicate arrives the same way (pp-tools
+    // passes one built on the seal leaf's hasRecordedVaultArtifacts). The resolver
+    // memoises it and asks it only for an enabled, config-inactive seal gate.
+    const resolveRecordedArtifacts = options['resolveRecordedArtifacts'];
+    const recordedArtifacts = () => resolveInjectedRecordedArtifacts(resolveRecordedArtifacts);
+    // Quick 261015-ect (QD-13): the bindings measurement arrives the same way
+    // (pp-tools passes one built on the vault leaf's hasPlatformBindings).
+    const resolvePlatformBindingsPresent = options['resolvePlatformBindingsPresent'];
+    const platformBindingsPresent = () => resolveInjectedPlatformBindingsPresent(resolvePlatformBindingsPresent);
+    let resolved;
+    try {
+        // --active-cap reads the UNFILTERED resolution (16-16 D-81, see above):
+        // without the bindings thunk, so it keeps answering the config switch.
+        resolved = resolveLoopHooks({
+            point, registry, config, cwd, capabilityStatesById, vaultMode, recordedArtifacts,
+            ...(activeCapId === undefined ? { platformBindingsPresent } : {}),
+        });
+    }
+    catch (err) {
+        const msg = (err instanceof Error) ? err.message : String(err);
+        coreError(msg);
         return;
     }
-    const resolved = outcome.resolved;
     // --active-cap mode: print exactly 'true' or 'false' with no envelope
     if (activeCapId !== undefined) {
-        const isActive = resolved.activeHooks.some((h) => h.capId === activeCapId);
+        // Phase 16 D-27 (research C-3): a hook rendering is no longer enough — the
+        // capability must itself be active. A seal gate renders for a config-
+        // inactive vault-practices, and the doors read `--active-cap` as their
+        // switch, so a seal must never make an inactive capability answer `true`.
+        // Equivalent to the old answer on every input without a seal: a normal
+        // hook renders only for an active capability.
+        const isActive = resolved.activeHooks.some((h) => h.capId === activeCapId)
+            && capabilityStatesById.get(activeCapId)?.active === true;
         process.stdout.write(isActive ? 'true\n' : 'false\n');
         return;
     }
     // --into mode: fragment text of the active contributions targeting <role>
     if (intoRole !== undefined) {
-        const texts = contributionsInto(resolved, intoRole).map((c) => c.fragment);
+        const texts = [];
+        for (const h of resolved.activeHooks) {
+            if (h.kind !== 'contribution' || h.into !== intoRole)
+                continue;
+            if (typeof h.fragment?.inline !== 'string')
+                continue;
+            texts.push(h.fragment.inline);
+        }
         if (texts.length > 0)
             process.stdout.write(texts.join('\n\n') + '\n');
         return;
@@ -553,11 +612,8 @@ function cmdLoopRenderHooks(cwd, point, raw, options = {}) {
         activeHooks: resolved.activeHooks,
         rendered,
     };
-    if (phaseTier) {
-        envelope.phase_tier = { phase: tierPhase, tier: phaseTier.tier, source: phaseTier.source, suppressed: phaseTier.suppressed };
-    }
-    if (outcome.warnings.length > 0) {
-        envelope.warnings = outcome.warnings;
+    if (state.warnings && state.warnings.length > 0) {
+        envelope.warnings = state.warnings;
     }
     // No rawValue third argument, so --raw emits the JSON envelope rather than
     // plain text. This is deliberate and load-bearing: 23 workflow call sites do
@@ -571,8 +627,6 @@ module.exports = {
     resolveLoopHooks,
     renderLoopHooks,
     cmdLoopRenderHooks,
-    resolveProjectLoopHooks,
-    contributionsInto,
     // Exported for tests
     _getNestedConfigValue,
     _resolveActivationValue,
@@ -580,6 +634,12 @@ module.exports = {
     // Re-exported for identity parity guard (FIX 2: resolveConfigValues in this module
     // calls resolveConfigKey; exporting it here makes the single-owner contract testable).
     resolveConfigKey,
+    // Re-exported for the same identity pin: the mode-filter rule has one owner,
+    // capability-state.cjs (Phase 15 D-02/D-28).
+    vaultModeFilterVerdict,
+    // Re-exported for the same identity pin: the seal rule has one owner,
+    // capability-state.cjs (Phase 16 D-19).
+    sealRenderVerdict,
     CANONICAL_POINTS_FALLBACK,
     CANONICAL_POINTS,
 };