principles-disciple 4.1.1 → 4.1.3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -1,203 +0,0 @@
1
- /**
2
- * Rule Host — Constrained execution layer for active code implementations
3
- *
4
- * PURPOSE: Load active code implementations from the SQLite activations table
5
- * (code_tool_hook channel), execute them in a constrained node:vm context,
6
- * and merge their decisions.
7
- *
8
- * ARCHITECTURE (PRI-436):
9
- * - SQLite is the SOLE production source of active RuleCode
10
- * - No filesystem ledger or implementation asset reads occur during evaluation
11
- * - Constructor takes stateDir for API compatibility (no longer used for impl loading)
12
- * - workspaceDir enables reading code_tool_hook activations from SQLite
13
- * - evaluate(input) loads active code implementations and runs them
14
- * - Each implementation executes in an isolated vm context with minimal helpers
15
- * - Decision merge: block short-circuits, requireApproval collects, allow is implicit
16
- *
17
- * SECURITY CONSTRAINTS (T-12-01, T-12-04):
18
- * - Candidate code loads through a dedicated vm context, not the host realm
19
- * - No importModuleDynamically callback
20
- * - Helpers are a frozen object — implementations cannot modify the helper surface
21
- *
22
- * CONSERVATIVE DEGRADATION (T-12-02, D-08):
23
- * - On ANY host error (load failure, eval error, vm error): return undefined
24
- * - Never throw, never bypass downstream gates (Progressive Gate, Edit Verification)
25
- */
26
- import type { RuleHostInput, RuleHostResult } from '@principles/core/runtime';
27
- import type { RuleHostLogger } from '@principles/core/runtime';
28
- export type { RuleHostLogger } from '@principles/core/runtime';
29
- export interface RuleHostOptions {
30
- /** Workspace directory for SQLite access. Required for RuleHost to load active code_tool_hook activations. */
31
- workspaceDir?: string;
32
- }
33
- type RuleHostActivationMode = 'shadow' | 'live';
34
- export interface RuleHostObservedDecision extends RuleHostResult {
35
- readonly activationId: string;
36
- }
37
- /**
38
- * PRI-491 — A structured record of an activation that was skipped at load
39
- * time (flag-off v2, unsupported action, unsupported context version,
40
- * missing target_ref, content_json not an object, no implementationCode,
41
- * or duplicate active activation for target_ref).
42
- *
43
- * Unlike compile/load failures (which emit rulehost_unhealthy), skipped
44
- * activations have a configuration/flag reason — the RuleCode itself may be
45
- * valid, but the runtime chose not to execute it. Duplicate activations are
46
- * a special case: they ALSO emit rulehost_unhealthy (for telemetry), but are
47
- * surfaced in skippedActivations so the owner can observe and act (rc-9).
48
- *
49
- * ERR-002 (rc-9): every skip carries a reason + nextAction, never silent.
50
- */
51
- export interface SkippedActivation {
52
- readonly activationId: string;
53
- readonly ruleId: string;
54
- /**
55
- * The mode the activation WOULD have had if loaded. Optional for cases
56
- * where the action itself is unrecognized (neither shadow nor live).
57
- */
58
- readonly mode?: RuleHostActivationMode;
59
- readonly reason: string;
60
- readonly nextAction: string;
61
- }
62
- export interface RuleHostEvaluationReport {
63
- readonly liveDecision: RuleHostResult | undefined;
64
- /**
65
- * P1 (ISSUE-023): live 聚合决策的溯源 — 贡献该决策的 live activation id
66
- * (经 ruleId 反查 implementationSources)。审计开放项: 414 次 live-mode
67
- * 评估无法对账到具体规则,因为 live 事件不带 activationId。
68
- */
69
- readonly liveDecisionActivationId?: string;
70
- readonly shadowDecisions: readonly RuleHostObservedDecision[];
71
- /**
72
- * PRI-491 — Activations that were skipped at load time. Empty when all
73
- * active activations loaded successfully. Each entry carries a structured
74
- * reason + nextAction so the owner can act without reading SQLite rows.
75
- */
76
- readonly skippedActivations: readonly SkippedActivation[];
77
- /**
78
- * PRI-567 — Number of live-mode implementations loaded for this evaluation.
79
- * Lets the gate distinguish "live rule evaluated → allow" from
80
- * "no live rules armed at all" (which previously both logged decision='allow',
81
- * making enforcement statistics read as if rules were active when none were).
82
- */
83
- readonly liveRulesLoaded: number;
84
- /** Distinguishes an empty live set from a failed evaluation. */
85
- readonly evaluationStatus: 'ok' | 'failed';
86
- }
87
- export declare class RuleHost {
88
- private readonly stateDir;
89
- private logger;
90
- private readonly workspaceDir;
91
- private readonly implementationSources;
92
- private activationFingerprint;
93
- private cachedImplementations;
94
- /**
95
- * PRI-491: Cached skipped activations from the last load. Returned alongside
96
- * cachedImplementations on fingerprint hit so evaluateDetailed can surface
97
- * them without re-scanning SQLite.
98
- */
99
- private cachedSkipped;
100
- private sqliteConnection;
101
- /**
102
- * R2-RH-002: Guards the "armed but empty" warn so it fires at most once per
103
- * RuleHost instance. Without this, the 0-rules path (workspaceDir missing OR
104
- * zero active code_tool_hook activations) returns [] silently on every
105
- * evaluation — an observability gap (rc-9-no-silent-fallback). The warn is
106
- * NOT a degradation fallback (RuleHost correctly has no opinion when empty);
107
- * it makes the empty-armed state visible so operators can investigate why
108
- * no live rules are loaded.
109
- */
110
- private emptyLoadWarnEmitted;
111
- /**
112
- * PRI-1044 step 3-1 (LOCKSTEP twin of the host-runtime gate): an ACTIVE
113
- * activation whose pi_artifacts row is gone is dropped by the INNER JOIN in
114
- * `_loadFromActivationsTable`, so the RuleHost silently enforces fewer rules
115
- * than the Owner armed. Suppression is keyed on the dangling descriptor SET
116
- * (not a one-shot latch, which would never re-arm on this cached singleton
117
- * instance): an unchanged set is not re-logged, a changed set is, and an
118
- * empty set clears the signature so a later recurrence warns again.
119
- */
120
- private danglingArtifactSignature;
121
- constructor(stateDir: string, logger?: RuleHostLogger, options?: RuleHostOptions);
122
- /**
123
- * Update the logger sink on a cached RuleHost instance.
124
- *
125
- * WorkspaceContext caches the RuleHost singleton, but each gate call may
126
- * pass a request-level logger. Without this update, warn/unhealthy logs
127
- * would forever go to the first logger sink, making the new path hard to
128
- * debug.
129
- */
130
- updateLogger(logger: RuleHostLogger): void;
131
- /**
132
- * Evaluate the input against all active code implementations.
133
- *
134
- * Returns:
135
- * - undefined when no active code implementations exist (no opinion)
136
- * - undefined when all implementations return allow or matched=false
137
- * - { decision: 'block', ... } when any implementation returns block (short-circuits)
138
- * - { decision: 'requireApproval', ... } when any implementation returns requireApproval
139
- */
140
- evaluate(input: RuleHostInput): RuleHostResult | undefined;
141
- dispose(): void;
142
- evaluateDetailed(input: RuleHostInput): RuleHostEvaluationReport;
143
- /**
144
- * Load active code implementations from the SQLite activations table.
145
- *
146
- * PRI-436: SQLite is the SOLE production source. The filesystem ledger
147
- * (principle-tree-ledger) and implementation asset paths have been deleted.
148
- * No fallback, no dual-source, no deprecated adapter.
149
- *
150
- * Source: activations table (code_tool_hook channel, deactivated_at IS NULL)
151
- * → JOIN pi_artifacts for content_json → extract implementationCode → compile
152
- */
153
- private _loadActiveCodeImplementations;
154
- /**
155
- * R2-RH-002: Emit the "armed but empty" warn at most once per RuleHost
156
- * instance. The warn is cached via `emptyLoadWarnEmitted` so repeated
157
- * evaluations (which all hit the empty path) do not spam the log.
158
- *
159
- * This is an observability signal, NOT a degradation fallback — RuleHost
160
- * correctly returns "no opinion" when there are no active rules. The warn
161
- * makes the empty state visible so operators can distinguish "RuleHost is
162
- * working but has no rules" from "RuleHost is broken" (rc-9-no-silent-fallback).
163
- */
164
- private _emitEmptyLoadWarn;
165
- /**
166
- * Load active code implementations from the activations table (code_tool_hook channel).
167
- *
168
- * For each activation record:
169
- * 1. Query the pi_artifacts table for the artifact content
170
- * 2. Parse content_json to extract implementationCode (treated as unknown, EP-01)
171
- * 3. Compile via loadRuleImplementationModule (isolated vm context)
172
- *
173
- * PRI-436 invariant: at most one active activation per rule (target_ref).
174
- * Duplicate active activations for the same target_ref are ALL skipped
175
- * (zero executions) and emit structured unhealthy evidence via logger.warn
176
- * (Runtime Contract Rule 9: graceful degradation includes a reason).
177
- *
178
- * All data from SQLite is treated as unknown and validated before use.
179
- */
180
- private _loadFromActivationsTable;
181
- /**
182
- * PRI-437: Record an unhealthy activation state to EventLog.
183
- *
184
- * This makes compile/load failures visible to CLI (pd runtime health) and
185
- * Console API — NOT just a logger.warn that's silently skipped.
186
- *
187
- * ERR-002: degradation includes a reason and nextAction (not silent).
188
- * Failures in EventLog recording are caught and logged (never throw).
189
- */
190
- private _recordUnhealthy;
191
- /**
192
- * PRI-491: Record a skipped activation to EventLog.
193
- *
194
- * Unlike _recordUnhealthy (compile/load failures), skipped activations have
195
- * a configuration/flag reason — the RuleCode itself may be valid, but the
196
- * runtime chose not to execute it (flag-off v2, unsupported context version,
197
- * unsupported action, content_json not object, no implementationCode).
198
- *
199
- * ERR-002: degradation includes a reason and nextAction (rc-9-no-silent-fallback).
200
- * Failures in EventLog recording are caught and logged (never throw).
201
- */
202
- private _recordSkipped;
203
- }