@principles/host-runtime 0.7.14 → 0.8.0

package/dist/prompt-injection-projection.js

@@ -1,7 +1,161 @@
-import { RUNTIME_V2_PRINCIPLE_BUDGET, computeFeatureFlagsFromConfig, trimToBudget, } from '@principles/core/runtime-v2';
+import { RUNTIME_V2_PRINCIPLE_BUDGET, computeFeatureFlagsFromConfig, renderPrinciplesToDirectives, trimToBudget, } from '@principles/core/runtime-v2';
 import { escapeXml } from '@principles/core/prompt-builder';
 import { loadPdConfigForPlugin } from './pd-config.js';
-import { buildActivePrinciplePromptContext, readPromptActivationCandidates } from './active-principle-prompt.js';
+import { buildActivePrinciplePromptContext, readPromptActivationCandidates, MAX_SHARED_DIAGNOSTIC_IDS } from './active-principle-prompt.js';
+import { readWorkspaceHostKindFacts } from './host-liveness-contract.js';
+export const PROMPT_INJECTION_TARGET_HOSTS = ['openclaw', 'codex'];
+export const PROMPT_INJECTION_UNIT = 'utf16_code_units';
+/**
+ * THE one route formula (P4): Codex always injects through the shared route
+ * (codex-adapter has no flag branch); OpenClaw routes by its
+ * `abstraction_layer_v1` gate. Every consumer that needs "which route would
+ * host X take" must call this — never re-type the ternary.
+ */
+export function promptRouteForHost(hostKind, flagEnabled) {
+    if (hostKind === 'codex')
+        return 'shared_render';
+    return flagEnabled ? 'shared_render' : 'legacy_trim';
+}
+function standardHostRoutes(flagEnabled) {
+    return [
+        { hostKind: 'openclaw', route: promptRouteForHost('openclaw', flagEnabled) },
+        { hostKind: 'codex', route: promptRouteForHost('codex', flagEnabled) },
+    ];
+}
+/**
+ * Resolve the effective route for this workspace. Pure read of existing
+ * config + provenance facts — no new registry, no persisted state.
+ */
+export function resolvePromptInjectionRouteDecision(input) {
+    const config = loadPdConfigForPlugin(input.workspaceDir);
+    const { flags } = computeFeatureFlagsFromConfig(config.effective);
+    const flagEnabled = flags.abstraction_layer_v1?.enabled === true;
+    const facts = readWorkspaceHostKindFacts(input.workspaceDir);
+    if (!config.ok) {
+        const [error] = config.errors;
+        return {
+            status: 'unconfirmed',
+            flagEnabled,
+            declaredHostKinds: facts.ok ? facts.declaredKinds : [],
+            effectiveHostKinds: facts.ok ? facts.effectiveKinds : [],
+            ...(!facts.ok ? { hostFactsStatus: 'unreadable' } : {}),
+            unconfirmedReason: `config_unreadable: ${error?.reason ?? 'workspace config is invalid'}`,
+            nextAction: error?.nextAction ?? 'repair .pd/config.yaml before measuring prompt injection',
+            perHost: standardHostRoutes(flagEnabled),
+        };
+    }
+    if (!flags.prompt?.enabled) {
+        return {
+            status: 'unconfirmed',
+            flagEnabled,
+            declaredHostKinds: facts.ok ? facts.declaredKinds : [],
+            effectiveHostKinds: facts.ok ? facts.effectiveKinds : [],
+            ...(!facts.ok ? { hostFactsStatus: 'unreadable' } : {}),
+            unconfirmedReason: 'prompt_feature_disabled: the prompt injection surface is off',
+            nextAction: 'set features.prompt.enabled=true in .pd/config.yaml',
+            perHost: standardHostRoutes(flagEnabled),
+        };
+    }
+    // Explicit request-level host is sufficient to bind the route even when
+    // workspace-wide host provenance is unreadable. Config and prompt state
+    // above remain mandatory preflight gates.
+    if (input.targetHost !== undefined) {
+        return {
+            status: 'confirmed',
+            hostKind: input.targetHost,
+            route: promptRouteForHost(input.targetHost, flagEnabled),
+            basis: 'explicit_target',
+            flagEnabled,
+            declaredHostKinds: facts.declaredKinds,
+            effectiveHostKinds: facts.ok ? facts.effectiveKinds : [],
+            ...(!facts.ok ? { hostFactsStatus: 'unreadable' } : {}),
+        };
+    }
+    if (!facts.ok) {
+        return {
+            status: 'unconfirmed',
+            flagEnabled,
+            declaredHostKinds: facts.declaredKinds,
+            effectiveHostKinds: [],
+            hostFactsStatus: 'unreadable',
+            unconfirmedReason: `host_facts_unreadable: ${facts.detail}`,
+            nextAction: facts.nextAction,
+            perHost: standardHostRoutes(flagEnabled),
+        };
+    }
+    const knownKinds = facts.effectiveKinds.filter((kind) => kind === 'openclaw' || kind === 'codex');
+    const unknownKinds = facts.effectiveKinds.filter((kind) => kind !== 'openclaw' && kind !== 'codex');
+    if (unknownKinds.length > 0) {
+        return {
+            status: 'unconfirmed',
+            flagEnabled,
+            declaredHostKinds: facts.declaredKinds,
+            effectiveHostKinds: facts.effectiveKinds,
+            unconfirmedReason: `unknown_host_kind_declared: ${unknownKinds.join(', ')} has no known prompt-injection route`,
+            nextAction: 'pass an explicit target host (openclaw|codex) for this request, or remove the unknown host declaration',
+            perHost: standardHostRoutes(flagEnabled),
+        };
+    }
+    if (knownKinds.length === 0) {
+        // No host ever operated this workspace. With the flag ON both standard
+        // hosts take the shared route, so the route IS confirmed; with the flag
+        // OFF they genuinely differ (OpenClaw list vs Codex shared) and there is
+        // no fact to pick one with — report unconfirmed instead of guessing.
+        if (flagEnabled) {
+            return {
+                status: 'confirmed',
+                route: 'shared_render',
+                basis: 'flag_shared_all_hosts',
+                flagEnabled,
+                declaredHostKinds: facts.declaredKinds,
+                effectiveHostKinds: facts.effectiveKinds,
+            };
+        }
+        return {
+            status: 'unconfirmed',
+            flagEnabled,
+            declaredHostKinds: facts.declaredKinds,
+            effectiveHostKinds: facts.effectiveKinds,
+            unconfirmedReason: 'no_host_facts_and_flag_off: no host declaration or host evidence exists, and the applicable hosts would take different routes',
+            nextAction: 'pass an explicit target host (openclaw|codex), or let a host run once in this workspace so it persists its declaration',
+            perHost: standardHostRoutes(flagEnabled),
+        };
+    }
+    if (knownKinds.length === 1) {
+        const [maybeHostKind] = knownKinds;
+        if (maybeHostKind !== undefined) {
+            return {
+                status: 'confirmed',
+                hostKind: maybeHostKind,
+                route: promptRouteForHost(maybeHostKind, flagEnabled),
+                basis: 'workspace_host_facts',
+                flagEnabled,
+                declaredHostKinds: facts.declaredKinds,
+                effectiveHostKinds: facts.effectiveKinds,
+            };
+        }
+    }
+    // Both openclaw and codex are applicable.
+    if (flagEnabled) {
+        return {
+            status: 'confirmed',
+            route: 'shared_render',
+            basis: 'flag_shared_all_hosts',
+            flagEnabled,
+            declaredHostKinds: facts.declaredKinds,
+            effectiveHostKinds: facts.effectiveKinds,
+        };
+    }
+    return {
+        status: 'unconfirmed',
+        flagEnabled,
+        declaredHostKinds: facts.declaredKinds,
+        effectiveHostKinds: facts.effectiveKinds,
+        unconfirmedReason: 'multi_host_routes_differ: openclaw would take the legacy list route and codex the shared route under the current flag-off config',
+        nextAction: 'pass an explicit target host (openclaw|codex) for this request, or enable abstraction_layer_v1 so both hosts share one route',
+        perHost: standardHostRoutes(flagEnabled),
+    };
+}
 /**
  * PR-1894: which activations a fair-rotation selector injects across the
  * whole ring. The plugin's round key advances by one per recorded user turn
@@ -24,18 +178,27 @@ function collectReachableActivationIds(principles, budget) {
     }
     return [...reachable];
 }
+function isDiagnosticCapHit(ids) {
+    return ids.length >= MAX_SHARED_DIAGNOSTIC_IDS;
+}
 /**
  * PR #1844 follow-up: forecast the prompt-injection budget from the SAME
- * projection the agent injection itself uses, routed by the same
- * `abstraction_layer_v1` flag the OpenClaw plugin's runtime gate reads:
+ * projection the agent injection itself uses:
  *
- * - legacy route (live default, flag OFF): activation candidates from
- *   `readPromptActivationCandidates` (same FIFO query + artifact resolve as
- *   the plugin's `PromptActivationReader`) trimmed by the REAL
- *   `trimToBudget` — identical input × ordering × trim logic as
- *   `openclaw-plugin/src/hooks/prompt.ts`.
- * - shared route (flag ON): delegate to `buildActivePrinciplePromptContext`,
- *   which IS the production shared path's projection source.
+ * - legacy route: activation candidates from `readPromptActivationCandidates`
+ *   (same FIFO query + artifact resolve as the plugin's list path) trimmed by
+ *   the REAL `trimToBudget` — identical input × ordering × trim logic as
+ *   `openclaw-plugin/src/hooks/prompt.ts`;
+ * - shared route: delegate to `buildActivePrinciplePromptContext`, which IS
+ *   the production shared path's projection source (Codex always; OpenClaw
+ *   when its `abstraction_layer_v1` gate is on).
+ *
+ * Route selection here is EXPLICIT: `targetHost: 'codex'` forces the shared
+ * route (production truth for Codex), `targetHost: 'openclaw'` follows the
+ * workspace flag, and no target follows the flag (the historical behavior —
+ * callers that lack host context should prefer
+ * `resolveLivePromptInjectionProjection`, which binds the route to real host
+ * facts and refuses to guess).
  *
  * Known conservative gap: the plugin's legacy route additionally dedups
  * candidates against the legacy evolution ledger before trimming; the
@@ -43,19 +206,21 @@ function collectReachableActivationIds(principles, budget) {
  * forecast slightly MORE consumption than the real injection (never less).
  *
  * PR-1894 — round-key alignment. The plugin derives its fair-rotation round
- * key from the CURRENT session's turn ordinal
- * (`nextSessionTurnOrdinal`), which the console has no access to. Passing no
- * key therefore does NOT make the forecast "more conservative": it selects a
- * DIFFERENT policy (`legacy_fifo_prefix_v1`) than the one production runs, and
- * legacy FIFO structurally excludes the newest activation from every
- * truncated selection. The console must either supply the round key or
- * report the policy honestly, so this function takes the key as an explicit
- * input and exposes `selectionPolicy` on the result.
+ * key from the CURRENT session's turn ordinal (`nextSessionTurnOrdinal`),
+ * which the console has no access to. Passing no key therefore does NOT make
+ * the forecast "more conservative": it selects a DIFFERENT policy
+ * (`legacy_fifo_prefix_v1`) than the one production runs. The console must
+ * either supply the round key or report the policy honestly, so this
+ * function takes the key as an explicit input and exposes
+ * `selectionPolicy` on the result.
  */
 export async function buildLivePromptInjectionProjection(input) {
-    const sharedRoute = computeFeatureFlagsFromConfig(loadPdConfigForPlugin(input.workspaceDir).effective).flags.abstraction_layer_v1?.enabled === true;
+    const flagEnabled = computeFeatureFlagsFromConfig(loadPdConfigForPlugin(input.workspaceDir).effective).flags.abstraction_layer_v1?.enabled === true;
+    const sharedRoute = input.targetHost === 'codex' ? true : flagEnabled;
     if (sharedRoute) {
         const context = await buildActivePrinciplePromptContext(input);
+        const oversized = context.oversizedActivationIds ?? [];
+        const dropped = context.droppedActivationIds ?? [];
         return {
             route: 'shared_render',
             budget: context.budget,
@@ -71,6 +236,12 @@ export async function buildLivePromptInjectionProjection(input) {
             eventuallyInjectedActivationIds: [],
             eligibleCount: context.eligibleCount ?? 0,
             productionRotates: false,
+            unit: PROMPT_INJECTION_UNIT,
+            budgetScope: 'full_directive_context',
+            oversizedActivationIds: oversized,
+            droppedActivationIds: dropped,
+            oversizedDiagnosticTruncated: isDiagnosticCapHit(oversized),
+            droppedDiagnosticTruncated: isDiagnosticCapHit(dropped),
         };
     }
     const candidates = await readPromptActivationCandidates(input);
@@ -88,6 +259,12 @@ export async function buildLivePromptInjectionProjection(input) {
             eventuallyInjectedActivationIds: [],
             eligibleCount: 0,
             productionRotates: false,
+            unit: PROMPT_INJECTION_UNIT,
+            budgetScope: 'selected_lines',
+            oversizedActivationIds: [],
+            droppedActivationIds: [],
+            oversizedDiagnosticTruncated: false,
+            droppedDiagnosticTruncated: false,
         };
     }
     // PR-1894: pass the caller's round key so the forecast runs the SAME
@@ -101,6 +278,7 @@ export async function buildLivePromptInjectionProjection(input) {
     // "queued behind rotation" apart from "structurally starved", otherwise it
     // keeps telling the Owner to deactivate healthy principles.
     const eventuallyInjectedActivationIds = collectReachableActivationIds(principles, RUNTIME_V2_PRINCIPLE_BUDGET);
+    const fullRenderChars = renderPrinciplesToDirectives(injected, trimmed.injectedIds, { escapeFn: escapeXml, selfReportInstruction: candidates.selfReportEnabled }).length;
     return {
         route: 'legacy_trim',
         budget: RUNTIME_V2_PRINCIPLE_BUDGET,
@@ -113,5 +291,31 @@ export async function buildLivePromptInjectionProjection(input) {
         eventuallyInjectedActivationIds,
         eligibleCount: trimmed.eligibleCount,
         productionRotates: true,
+        unit: PROMPT_INJECTION_UNIT,
+        budgetScope: 'selected_lines',
+        oversizedActivationIds: trimmed.oversizedActivationIds,
+        droppedActivationIds: trimmed.droppedActivationIds,
+        oversizedDiagnosticTruncated: isDiagnosticCapHit(trimmed.oversizedActivationIds),
+        droppedDiagnosticTruncated: isDiagnosticCapHit(trimmed.droppedActivationIds),
+        ...(injected.length > 0 ? { fullRenderChars } : {}),
     };
 }
+export async function resolveLivePromptInjectionProjection(input) {
+    const decision = resolvePromptInjectionRouteDecision(input);
+    if (decision.status === 'confirmed') {
+        const projection = await buildLivePromptInjectionProjection({
+            ...input,
+            targetHost: decision.hostKind,
+        });
+        return { status: 'confirmed', decision, projection };
+    }
+    const hosts = decision.perHost?.map((entry) => entry.hostKind) ?? [...PROMPT_INJECTION_TARGET_HOSTS];
+    const perHost = [];
+    for (const hostKind of hosts) {
+        perHost.push({
+            hostKind,
+            projection: await buildLivePromptInjectionProjection({ ...input, targetHost: hostKind }),
+        });
+    }
+    return { status: 'unconfirmed', decision, perHost };
+}

package/dist/prompt-injection-status.d.ts

@@ -0,0 +1,44 @@
+import { type PromptInjectionBudgetScope, type PromptInjectionRouteDecision, type PromptInjectionRouteName, type PromptInjectionTargetHost } from './prompt-injection-projection.js';
+/**
+ * SPEC PD_PROMPT_CAPACITY_V1 R-A3: per-live-activation injection status for
+ * the activations surface. Every row carries POSITIVE single-item evidence
+ * computed with the production serializer for the bound route — "oversized"
+ * means this row's own serialized entry exceeds the budget, "window_excluded"
+ * means it fits but the current window is full (AC-06: a row is never deemed
+ * healthy merely because it is absent from a bounded diagnostic list), and
+ * `route_unconfirmed` surfaces AC-01's honest unknown instead of a guess.
+ * No compliance/遵守 counts are produced here — absence of injection logs is
+ * NOT reported as "zero compliance" (AC-12 boundary).
+ */
+export type PromptActivationInjectionStatusKind = 'injectable' | 'oversized' | 'window_excluded' | 'resolution_failed' | 'route_unconfirmed';
+export interface PromptActivationInjectionStatus {
+    activationId: string;
+    principleId?: string;
+    status: PromptActivationInjectionStatusKind;
+    /** Present for injectable/window_excluded/oversized under a confirmed route. */
+    inCurrentWindow?: boolean;
+    /** Present when the single-item cost was computable. */
+    costChars?: number;
+    budget?: number;
+    budgetScope?: PromptInjectionBudgetScope;
+    route?: PromptInjectionRouteName;
+    /** Present for resolution_failed / route_unconfirmed (structured reason). */
+    reason?: string;
+    /** Present for route_unconfirmed: per-host single-item fit facts. */
+    perHostFits?: readonly {
+        hostKind: PromptInjectionTargetHost;
+        fits: boolean;
+    }[];
+}
+export interface PromptActivationInjectionStatusReport {
+    route: PromptInjectionRouteDecision;
+    /** Empty when injection is globally unavailable (prompt flag off / state.db missing) — see `globalReason`. */
+    statuses: PromptActivationInjectionStatus[];
+    warnings: string[];
+    /** Present when no status could be computed at all (fail-loud degradation, rc-9). */
+    globalReason?: string;
+}
+export declare function readPromptActivationInjectionStatuses(input: {
+    workspaceDir: string;
+    targetHost?: PromptInjectionTargetHost;
+}): Promise<PromptActivationInjectionStatusReport>;

package/dist/prompt-injection-status.js

@@ -0,0 +1,147 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { RUNTIME_V2_PRINCIPLE_BUDGET, SqliteActivationStateStore, SqliteConnection, SqlitePIArtifactStore, computeFeatureFlagsFromConfig, filterPromptActivations, resolvePrincipleFromArtifact, } from '@principles/core/runtime-v2';
+import { loadPdConfigForPlugin } from './pd-config.js';
+import { computePromptSingleItemFit } from './prompt-activation-deliverability.js';
+import { PROMPT_INJECTION_TARGET_HOSTS, buildLivePromptInjectionProjection, promptRouteForHost, resolvePromptInjectionRouteDecision, } from './prompt-injection-projection.js';
+export async function readPromptActivationInjectionStatuses(input) {
+    const config = loadPdConfigForPlugin(input.workspaceDir);
+    const warnings = [];
+    if (!config.ok) {
+        warnings.push(...config.errors.map((error) => `config_invalid: ${error.reason}; nextAction=${error.nextAction}`));
+    }
+    const { flags } = computeFeatureFlagsFromConfig(config.effective);
+    const selfReportEnabled = flags.principle_receipt_self_report?.enabled === true;
+    const route = resolvePromptInjectionRouteDecision(input);
+    if (!flags.prompt?.enabled) {
+        return {
+            route,
+            statuses: [],
+            warnings,
+            globalReason: 'prompt_feature_disabled: the prompt injection surface is off, so no activation can be injected; nextAction=set features.prompt.enabled=true in .pd/config.yaml',
+        };
+    }
+    const stateDbPath = path.join(input.workspaceDir, '.pd', 'state.db');
+    if (!fs.existsSync(stateDbPath)) {
+        return {
+            route,
+            statuses: [],
+            warnings,
+            globalReason: 'activation_db_not_found: .pd/state.db is missing, live activations cannot be read; nextAction=initialize_workspace_runtime_state',
+        };
+    }
+    const rows = [];
+    let connection;
+    try {
+        connection = new SqliteConnection({ workspaceDir: input.workspaceDir, readonly: true, bootstrapIfMissing: false });
+        const activations = filterPromptActivations(await new SqliteActivationStateStore(connection).listPromptActivations());
+        const artifactStore = new SqlitePIArtifactStore(connection);
+        for (const activation of activations) {
+            let artifact;
+            try {
+                artifact = await artifactStore.getArtifactById(activation.artifactId);
+            }
+            catch (error) {
+                const message = error instanceof Error ? error.message : String(error);
+                rows.push({ activationId: activation.activationId, failure: `artifact_query_failed: ${message}` });
+                continue;
+            }
+            if (artifact === null) {
+                rows.push({ activationId: activation.activationId, failure: `artifact_not_found: artifactId=${activation.artifactId}` });
+                continue;
+            }
+            const resolved = resolvePrincipleFromArtifact({
+                artifact_id: artifact.artifactId,
+                artifact_kind: artifact.artifactKind,
+                content_json: artifact.contentJson,
+                validation_status: artifact.validationStatus,
+            }, activation);
+            if (!resolved.ok) {
+                rows.push({ activationId: activation.activationId, failure: resolved.warning });
+                continue;
+            }
+            rows.push({
+                activationId: activation.activationId,
+                principleId: resolved.principle.principleId,
+                text: resolved.principle.text,
+            });
+        }
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        return {
+            route,
+            statuses: [],
+            warnings,
+            globalReason: `activation_db_unreadable: ${message}; nextAction=check_workspace_pd_state_db`,
+        };
+    }
+    finally {
+        connection?.close();
+    }
+    if (route.status === 'unconfirmed') {
+        const statuses = rows.map((row) => {
+            if ('failure' in row) {
+                return { activationId: row.activationId, status: 'resolution_failed', reason: row.failure };
+            }
+            const perHostFits = PROMPT_INJECTION_TARGET_HOSTS.map((hostKind) => {
+                const hostRoute = promptRouteForHost(hostKind, route.flagEnabled);
+                const { fits } = computePromptSingleItemFit({
+                    principle: { principleId: row.principleId, text: row.text, artifactId: '', activationId: row.activationId },
+                    route: hostRoute,
+                    selfReportEnabled,
+                });
+                return { hostKind, fits };
+            });
+            return {
+                activationId: row.activationId,
+                principleId: row.principleId,
+                status: 'route_unconfirmed',
+                reason: route.unconfirmedReason ?? 'effective injection route cannot be confirmed',
+                perHostFits,
+            };
+        });
+        return { route, statuses, warnings };
+    }
+    const projection = await buildLivePromptInjectionProjection({
+        workspaceDir: input.workspaceDir,
+        targetHost: route.hostKind,
+    });
+    warnings.push(...projection.warnings);
+    const statuses = rows.map((row) => {
+        if ('failure' in row) {
+            return { activationId: row.activationId, status: 'resolution_failed', reason: row.failure };
+        }
+        const { fits, costChars } = computePromptSingleItemFit({
+            principle: { principleId: row.principleId, text: row.text, artifactId: '', activationId: row.activationId },
+            route: projection.route,
+            selfReportEnabled,
+        });
+        const inCurrentWindow = projection.injectedActivationIds.includes(row.activationId);
+        const budgetScope = projection.budgetScope;
+        if (!fits) {
+            return {
+                activationId: row.activationId,
+                principleId: row.principleId,
+                status: 'oversized',
+                inCurrentWindow: false,
+                costChars,
+                budget: RUNTIME_V2_PRINCIPLE_BUDGET,
+                budgetScope,
+                route: projection.route,
+                reason: `single_item_exceeds_budget: this principle's own entry is ${costChars} chars > ${RUNTIME_V2_PRINCIPLE_BUDGET} under the ${projection.route === 'shared_render' ? 'full directive render' : 'list entry'} serialization`,
+            };
+        }
+        return {
+            activationId: row.activationId,
+            principleId: row.principleId,
+            status: inCurrentWindow ? 'injectable' : 'window_excluded',
+            inCurrentWindow,
+            costChars,
+            budget: RUNTIME_V2_PRINCIPLE_BUDGET,
+            budgetScope,
+            route: projection.route,
+        };
+    });
+    return { route, statuses, warnings };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@principles/host-runtime",
-  "version": "0.7.14",
+  "version": "0.8.0",
   "description": "Shared host-neutral orchestration for Principles Disciple MVP-Core hook paths.",
   "type": "module",
   "main": "./dist/index.js",
@@ -21,7 +21,7 @@
     "lint": "eslint \"src/**/*.ts\""
   },
   "dependencies": {
-    "@principles/core": "^1.289.1",
+    "@principles/core": "^1.290.0",
     "@principles/install-layout": "^0.2.7",
     "better-sqlite3": "^13.0.3",
     "js-yaml": "^5.4.1"