@principles/core 1.73.0

package/dist/pain-flag-resolver.js

@@ -0,0 +1,21 @@
+/**
+ * PainFlagPathResolver — Pure function for resolving pain flag file paths.
+ *
+ * D-04: resolvePainFlagPath(workspaceDir: string): string
+ *
+ * Usage:
+ *   import { resolvePainFlagPath } from '@principles/core';
+ *   const flagPath = resolvePainFlagPath('/path/to/workspace');
+ *   // => '/path/to/workspace/.state/.pain_flag'
+ */
+import * as path from 'path';
+/**
+ * Resolve the absolute path to the .pain_flag file for a given workspace.
+ *
+ * @param workspaceDir - Absolute path to the workspace directory
+ * @returns The absolute path to the .pain_flag file
+ */
+export function resolvePainFlagPath(workspaceDir) {
+    return path.join(workspaceDir, '.state', '.pain_flag');
+}
+//# sourceMappingURL=pain-flag-resolver.js.map

package/dist/pain-flag-resolver.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"pain-flag-resolver.js","sourceRoot":"","sources":["../src/pain-flag-resolver.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,IAAI,MAAM,MAAM,CAAC;AAE7B;;;;;GAKG;AACH,MAAM,UAAU,mBAAmB,CAAC,YAAoB;IACtD,OAAO,IAAI,CAAC,IAAI,CAAC,YAAY,EAAE,QAAQ,EAAE,YAAY,CAAC,CAAC;AACzD,CAAC"}

package/dist/pain-recorder.d.ts

@@ -0,0 +1,38 @@
+/**
+ * PainRecorder — Pure function for recording pain signals.
+ *
+ * D-02: PainRecorder as pure function, decoupled from OpenClawPluginApi.
+ *
+ * Usage:
+ *   import { recordPainSignal } from '@principles/core';
+ *   const signal = await recordPainSignal(
+ *     { reason: 'edited file without reading first', source: 'manual', score: 75 },
+ *     '/path/to/workspace'
+ *   );
+ *
+ * Runtime V2 note:
+ * This helper no longer writes .state/.pain_flag. Manual diagnosis requests
+ * must use `pd pain record`, and OpenClaw runtime events must use
+ * PainSignalBridge/emitPainDetectedEvent.
+ */
+import type { PainSignal } from './pain-signal.js';
+/** Input shape for recordPainSignal. */
+export interface PainSignalInput {
+    reason: string;
+    source?: string;
+    score?: number;
+    sessionId?: string;
+    is_risky?: boolean;
+}
+/**
+ * Validate and normalize a pain signal.
+ *
+ * This does not write .state/.pain_flag. It remains as an SDK validation
+ * helper for callers that need a framework-agnostic PainSignal object.
+ *
+ * @param input - PainSignalInput (reason required, source/score optional)
+ * @param workspaceDir - Kept for API compatibility; not used for file writes.
+ * @returns Promise resolving to a validated PainSignal
+ */
+export declare function recordPainSignal(input: PainSignalInput, workspaceDir: string): Promise<PainSignal>;
+//# sourceMappingURL=pain-recorder.d.ts.map

package/dist/pain-recorder.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pain-recorder.d.ts","sourceRoot":"","sources":["../src/pain-recorder.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAGH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAEnD,wCAAwC;AACxC,MAAM,WAAW,eAAe;IAC9B,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB;AAED;;;;;;;;;GASG;AACH,wBAAsB,gBAAgB,CACpC,KAAK,EAAE,eAAe,EACtB,YAAY,EAAE,MAAM,GACnB,OAAO,CAAC,UAAU,CAAC,CAoCrB"}

package/dist/pain-recorder.js

@@ -0,0 +1,62 @@
+/**
+ * PainRecorder — Pure function for recording pain signals.
+ *
+ * D-02: PainRecorder as pure function, decoupled from OpenClawPluginApi.
+ *
+ * Usage:
+ *   import { recordPainSignal } from '@principles/core';
+ *   const signal = await recordPainSignal(
+ *     { reason: 'edited file without reading first', source: 'manual', score: 75 },
+ *     '/path/to/workspace'
+ *   );
+ *
+ * Runtime V2 note:
+ * This helper no longer writes .state/.pain_flag. Manual diagnosis requests
+ * must use `pd pain record`, and OpenClaw runtime events must use
+ * PainSignalBridge/emitPainDetectedEvent.
+ */
+import { validatePainSignal, deriveSeverity } from './pain-signal.js';
+/**
+ * Validate and normalize a pain signal.
+ *
+ * This does not write .state/.pain_flag. It remains as an SDK validation
+ * helper for callers that need a framework-agnostic PainSignal object.
+ *
+ * @param input - PainSignalInput (reason required, source/score optional)
+ * @param workspaceDir - Kept for API compatibility; not used for file writes.
+ * @returns Promise resolving to a validated PainSignal
+ */
+export async function recordPainSignal(input, workspaceDir) {
+    void workspaceDir;
+    // Validate required fields
+    if (!input.reason || !input.reason.trim()) {
+        throw new Error('PainSignalInput.reason is required and must be non-empty');
+    }
+    const timestamp = new Date().toISOString();
+    const severity = deriveSeverity(input.score ?? 80);
+    // Build PainSignal-compatible object for schema validation
+    const rawSignal = {
+        source: input.source ?? 'manual',
+        score: input.score ?? 80,
+        timestamp,
+        reason: input.reason.trim(),
+        sessionId: input.sessionId ?? 'unknown',
+        agentId: 'principles-core', // SDK does not have agent identity
+        traceId: 'sdk', // SDK does not have trace context
+        triggerTextPreview: input.reason.slice(0, 100),
+        version: '0.1.0',
+        domain: 'coding',
+        severity,
+        context: {},
+    };
+    // Validate against schema (fills defaults for optional fields)
+    const result = validatePainSignal(rawSignal);
+    if (!result.valid) {
+        throw new Error(`Invalid PainSignal: ${result.errors.join(', ')}`);
+    }
+    const { signal } = result;
+    if (!signal)
+        throw new Error('Unexpected: validated PainSignal is undefined');
+    return signal;
+}
+//# sourceMappingURL=pain-recorder.js.map

package/dist/pain-recorder.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"pain-recorder.js","sourceRoot":"","sources":["../src/pain-recorder.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,EAAE,kBAAkB,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAYtE;;;;;;;;;GASG;AACH,MAAM,CAAC,KAAK,UAAU,gBAAgB,CACpC,KAAsB,EACtB,YAAoB;IAEpB,KAAK,YAAY,CAAC;IAClB,2BAA2B;IAC3B,IAAI,CAAC,KAAK,CAAC,MAAM,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,IAAI,EAAE,EAAE,CAAC;QAC1C,MAAM,IAAI,KAAK,CAAC,0DAA0D,CAAC,CAAC;IAC9E,CAAC;IAED,MAAM,SAAS,GAAG,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC;IAC3C,MAAM,QAAQ,GAAG,cAAc,CAAC,KAAK,CAAC,KAAK,IAAI,EAAE,CAAC,CAAC;IAEnD,2DAA2D;IAC3D,MAAM,SAAS,GAAG;QAChB,MAAM,EAAE,KAAK,CAAC,MAAM,IAAI,QAAQ;QAChC,KAAK,EAAE,KAAK,CAAC,KAAK,IAAI,EAAE;QACxB,SAAS;QACT,MAAM,EAAE,KAAK,CAAC,MAAM,CAAC,IAAI,EAAE;QAC3B,SAAS,EAAE,KAAK,CAAC,SAAS,IAAI,SAAS;QACvC,OAAO,EAAE,iBAAiB,EAAE,mCAAmC;QAC/D,OAAO,EAAE,KAAK,EAAc,kCAAkC;QAC9D,kBAAkB,EAAE,KAAK,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,EAAE,GAAG,CAAC;QAC9C,OAAO,EAAE,OAAO;QAChB,MAAM,EAAE,QAAQ;QAChB,QAAQ;QACR,OAAO,EAAE,EAAE;KACZ,CAAC;IAEF,+DAA+D;IAC/D,MAAM,MAAM,GAAG,kBAAkB,CAAC,SAAS,CAAC,CAAC;IAC7C,IAAI,CAAC,MAAM,CAAC,KAAK,EAAE,CAAC;QAClB,MAAM,IAAI,KAAK,CAAC,uBAAuB,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IACrE,CAAC;IAED,MAAM,EAAC,MAAM,EAAC,GAAG,MAAM,CAAC;IACxB,IAAI,CAAC,MAAM;QAAE,MAAM,IAAI,KAAK,CAAC,+CAA+C,CAAC,CAAC;IAE9E,OAAO,MAAM,CAAC;AAChB,CAAC"}

package/dist/pain-signal-adapter.d.ts

@@ -0,0 +1,37 @@
+/**
+ * PainSignalAdapter interface for the Evolution SDK.
+ *
+ * This interface decouples the evolution engine from specific AI agent
+ * frameworks (OpenClaw, Claude Code, etc.). All modules that need to
+ * capture pain signals from tool failures should depend on this interface
+ * rather than importing framework-specific event types directly.
+ *
+ * The interface uses a generic type parameter for the raw framework event,
+ * so each framework implementation provides its own concrete type.
+ */
+import type { PainSignal } from './pain-signal.js';
+/**
+ * Framework-agnostic adapter for capturing pain signals.
+ *
+ * @typeParam TRawEvent - The framework-specific event type
+ * (e.g., PluginHookAfterToolCallEvent for OpenClaw)
+ */
+export interface PainSignalAdapter<TRawEvent> {
+    /**
+     * Translate a framework-specific event into a universal PainSignal.
+     *
+     * Returns null when the event does not constitute a pain signal:
+     *  - "Not applicable": event type is not a failure (e.g., tool succeeded)
+     *  - "Malformed": required fields are missing or invalid (e.g., no sessionId)
+     *
+     * In both cases null is returned -- callers do not need to distinguish.
+     * This method performs pure translation only. Trigger decision logic
+     * (e.g., GFI threshold checks, tool name filtering) stays in the
+     * framework-side hook logic. Per D-02, capture() only translates.
+     *
+     * @param rawEvent - The framework-specific event to translate
+     * @returns A valid PainSignal, or null if the event does not produce one
+     */
+    capture(rawEvent: TRawEvent): PainSignal | null;
+}
+//# sourceMappingURL=pain-signal-adapter.d.ts.map

package/dist/pain-signal-adapter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pain-signal-adapter.d.ts","sourceRoot":"","sources":["../src/pain-signal-adapter.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AACH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAMnD;;;;;GAKG;AACH,MAAM,WAAW,iBAAiB,CAAC,SAAS;IAC1C;;;;;;;;;;;;;;OAcG;IACH,OAAO,CAAC,QAAQ,EAAE,SAAS,GAAG,UAAU,GAAG,IAAI,CAAC;CACjD"}

package/dist/pain-signal-adapter.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=pain-signal-adapter.js.map

package/dist/pain-signal-adapter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"pain-signal-adapter.js","sourceRoot":"","sources":["../src/pain-signal-adapter.ts"],"names":[],"mappings":""}

package/dist/pain-signal.d.ts

@@ -0,0 +1,76 @@
+/**
+ * Universal PainSignal schema for the Evolution SDK.
+ *
+ * This module defines a framework-agnostic pain signal that any AI agent
+ * framework can produce. It extends the existing PainFlagData format with
+ * additional structured fields (domain, severity, context) needed for
+ * cross-workspace evolution and multi-domain support.
+ *
+ * Validation uses @sinclair/typebox to match existing project patterns.
+ */
+import { type Static } from '@sinclair/typebox';
+/**
+ * Severity levels derived from pain score thresholds.
+ * - low:      0-39  (minor issue, informational)
+ * - medium:   40-69 (moderate error)
+ * - high:     70-89 (severe violation)
+ * - critical: 90-100 (systemic failure, spiral detected)
+ */
+export declare const PainSeverity: import("@sinclair/typebox").TUnion<[import("@sinclair/typebox").TLiteral<"low">, import("@sinclair/typebox").TLiteral<"medium">, import("@sinclair/typebox").TLiteral<"high">, import("@sinclair/typebox").TLiteral<"critical">]>;
+export type PainSeverity = Static<typeof PainSeverity>;
+/**
+ * TypeBox schema for a universal pain signal.
+ *
+ * Every signal MUST have: source, score, timestamp, reason, sessionId,
+ * agentId, traceId, triggerTextPreview. Optional fields (domain, severity,
+ * context) default during validation.
+ */
+export declare const PainSignalSchema: import("@sinclair/typebox").TObject<{
+    /** What triggered this pain signal (e.g., 'tool_failure', 'human_intervention') */
+    source: import("@sinclair/typebox").TString;
+    /** Pain score 0-100 */
+    score: import("@sinclair/typebox").TNumber;
+    /** ISO 8601 timestamp */
+    timestamp: import("@sinclair/typebox").TString;
+    /** Human-readable reason / error description */
+    reason: import("@sinclair/typebox").TString;
+    /** Session ID — identifies which conversation this happened in */
+    sessionId: import("@sinclair/typebox").TString;
+    /** Agent ID — identifies which agent (main, builder, diagnostician, etc.) */
+    agentId: import("@sinclair/typebox").TString;
+    /** Correlation trace ID for linking events across the pipeline */
+    traceId: import("@sinclair/typebox").TString;
+    /** Preview of the text that triggered this pain */
+    triggerTextPreview: import("@sinclair/typebox").TString;
+    /** Schema version for forward compatibility (e.g., '0.1.0') */
+    version: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+    /** Domain context (e.g., 'coding', 'writing', 'analysis') */
+    domain: import("@sinclair/typebox").TString;
+    /** Severity level derived from score */
+    severity: import("@sinclair/typebox").TUnion<[import("@sinclair/typebox").TLiteral<"low">, import("@sinclair/typebox").TLiteral<"medium">, import("@sinclair/typebox").TLiteral<"high">, import("@sinclair/typebox").TLiteral<"critical">]>;
+    /** Additional structured context payload */
+    context: import("@sinclair/typebox").TRecord<import("@sinclair/typebox").TString, import("@sinclair/typebox").TUnknown>;
+}>;
+export type PainSignal = Static<typeof PainSignalSchema>;
+/**
+ * Derives severity from a numeric pain score.
+ */
+export declare function deriveSeverity(score: number): PainSeverity;
+export interface PainSignalValidationResult {
+    valid: boolean;
+    errors: string[];
+    signal?: PainSignal;
+}
+/**
+ * Validates an arbitrary object against the PainSignal schema.
+ *
+ * Returns a structured result with:
+ * - `valid`: whether the input conforms to the schema
+ * - `errors`: human-readable list of validation failures
+ * - `signal`: the typed signal (only present when valid)
+ *
+ * Missing optional fields (domain, severity, context, version) are filled with defaults
+ * before validation so callers get a fully-formed signal back.
+ */
+export declare function validatePainSignal(input: unknown): PainSignalValidationResult;
+//# sourceMappingURL=pain-signal.d.ts.map

package/dist/pain-signal.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pain-signal.d.ts","sourceRoot":"","sources":["../src/pain-signal.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,OAAO,EAAQ,KAAK,MAAM,EAAE,MAAM,mBAAmB,CAAC;AAOtD;;;;;;GAMG;AACH,eAAO,MAAM,YAAY,mOAKvB,CAAC;AAGH,MAAM,MAAM,YAAY,GAAG,MAAM,CAAC,OAAO,YAAY,CAAC,CAAC;AAEvD;;;;;;GAMG;AACH,eAAO,MAAM,gBAAgB;IAC3B,mFAAmF;;IAEnF,uBAAuB;;IAEvB,yBAAyB;;IAEzB,gDAAgD;;IAEhD,kEAAkE;;IAElE,6EAA6E;;IAE7E,kEAAkE;;IAElE,mDAAmD;;IAEnD,+DAA+D;;IAE/D,6DAA6D;;IAE7D,wCAAwC;;IAExC,4CAA4C;;EAE5C,CAAC;AAEH,MAAM,MAAM,UAAU,GAAG,MAAM,CAAC,OAAO,gBAAgB,CAAC,CAAC;AAMzD;;GAEG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,MAAM,GAAG,YAAY,CAK1D;AAMD,MAAM,WAAW,0BAA0B;IACzC,KAAK,EAAE,OAAO,CAAC;IACf,MAAM,EAAE,MAAM,EAAE,CAAC;IACjB,MAAM,CAAC,EAAE,UAAU,CAAC;CACrB;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,OAAO,GAAG,0BAA0B,CAgD7E"}

package/dist/pain-signal.js

@@ -0,0 +1,125 @@
+/**
+ * Universal PainSignal schema for the Evolution SDK.
+ *
+ * This module defines a framework-agnostic pain signal that any AI agent
+ * framework can produce. It extends the existing PainFlagData format with
+ * additional structured fields (domain, severity, context) needed for
+ * cross-workspace evolution and multi-domain support.
+ *
+ * Validation uses @sinclair/typebox to match existing project patterns.
+ */
+import { Type } from '@sinclair/typebox';
+import { Value } from '@sinclair/typebox/value';
+// ---------------------------------------------------------------------------
+// PainSignal Schema
+// ---------------------------------------------------------------------------
+/**
+ * Severity levels derived from pain score thresholds.
+ * - low:      0-39  (minor issue, informational)
+ * - medium:   40-69 (moderate error)
+ * - high:     70-89 (severe violation)
+ * - critical: 90-100 (systemic failure, spiral detected)
+ */
+export const PainSeverity = Type.Union([
+    Type.Literal('low'),
+    Type.Literal('medium'),
+    Type.Literal('high'),
+    Type.Literal('critical'),
+]);
+/**
+ * TypeBox schema for a universal pain signal.
+ *
+ * Every signal MUST have: source, score, timestamp, reason, sessionId,
+ * agentId, traceId, triggerTextPreview. Optional fields (domain, severity,
+ * context) default during validation.
+ */
+export const PainSignalSchema = Type.Object({
+    /** What triggered this pain signal (e.g., 'tool_failure', 'human_intervention') */
+    source: Type.String({ minLength: 1 }),
+    /** Pain score 0-100 */
+    score: Type.Number({ minimum: 0, maximum: 100 }),
+    /** ISO 8601 timestamp */
+    timestamp: Type.String({ minLength: 1 }),
+    /** Human-readable reason / error description */
+    reason: Type.String({ minLength: 1 }),
+    /** Session ID — identifies which conversation this happened in */
+    sessionId: Type.String({ minLength: 1 }),
+    /** Agent ID — identifies which agent (main, builder, diagnostician, etc.) */
+    agentId: Type.String({ minLength: 1 }),
+    /** Correlation trace ID for linking events across the pipeline */
+    traceId: Type.String({ minLength: 1 }),
+    /** Preview of the text that triggered this pain */
+    triggerTextPreview: Type.String(),
+    /** Schema version for forward compatibility (e.g., '0.1.0') */
+    version: Type.Optional(Type.String({ default: '0.1.0' })),
+    /** Domain context (e.g., 'coding', 'writing', 'analysis') */
+    domain: Type.String({ default: 'coding' }),
+    /** Severity level derived from score */
+    severity: PainSeverity,
+    /** Additional structured context payload */
+    context: Type.Record(Type.String(), Type.Unknown()),
+});
+// ---------------------------------------------------------------------------
+// Default Derivation
+// ---------------------------------------------------------------------------
+/**
+ * Derives severity from a numeric pain score.
+ */
+export function deriveSeverity(score) {
+    if (score >= 90)
+        return 'critical';
+    if (score >= 70)
+        return 'high';
+    if (score >= 40)
+        return 'medium';
+    return 'low';
+}
+/**
+ * Validates an arbitrary object against the PainSignal schema.
+ *
+ * Returns a structured result with:
+ * - `valid`: whether the input conforms to the schema
+ * - `errors`: human-readable list of validation failures
+ * - `signal`: the typed signal (only present when valid)
+ *
+ * Missing optional fields (domain, severity, context, version) are filled with defaults
+ * before validation so callers get a fully-formed signal back.
+ */
+export function validatePainSignal(input) {
+    if (typeof input !== 'object' || input === null || Array.isArray(input)) {
+        return { valid: false, errors: ['Input must be a non-null object'] };
+    }
+    const raw = input;
+    // Apply defaults for optional fields before validation
+    const hydrated = {
+        ...raw,
+        domain: raw.domain ?? 'coding',
+        version: raw.version ?? '0.1.0',
+        severity: raw.severity ?? deriveSeverity(typeof raw.score === 'number' ? raw.score : 0),
+        context: raw.context ?? {},
+    };
+    // Security: enforce context size limit to prevent memory exhaustion
+    const MAX_CONTEXT_SIZE = 10_000;
+    if (JSON.stringify(hydrated.context).length > MAX_CONTEXT_SIZE) {
+        return { valid: false, errors: ['Context object exceeds maximum size (10KB)'] };
+    }
+    // Validate ISO 8601 timestamp format
+    if (typeof hydrated.timestamp === 'string' &&
+        isNaN(Date.parse(hydrated.timestamp))) {
+        return { valid: false, errors: ['timestamp must be a valid ISO 8601 date string'] };
+    }
+    // Collect TypeBox errors using Decode (strict, not Cast which coerces)
+    const errors = [...Value.Errors(PainSignalSchema, hydrated)];
+    if (errors.length > 0) {
+        return {
+            valid: false,
+            errors: errors.map((e) => `${e.path ? `${e.path}: ` : ''}${e.message}`),
+        };
+    }
+    return {
+        valid: true,
+        errors: [],
+        signal: Value.Cast(PainSignalSchema, hydrated),
+    };
+}
+//# sourceMappingURL=pain-signal.js.map

package/dist/pain-signal.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"pain-signal.js","sourceRoot":"","sources":["../src/pain-signal.ts"],"names":[],"mappings":"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"}

package/dist/principle-injector.d.ts

@@ -0,0 +1,67 @@
+/**
+ * PrincipleInjector interface and DefaultPrincipleInjector implementation for the Evolution SDK.
+ *
+ * The DefaultPrincipleInjector is a minimal framework-agnostic implementation that:
+ * - Sorts principles by priority (P0 first), then by creation date
+ * - Selects principles that fit within budgetChars
+ * - Always includes P0 principles (forced inclusion)
+ * - Formats principles as "- [ID] text"
+ *
+ * This implementation does NOT depend on openclaw-plugin internals.
+ * It uses only SDK types (InjectablePrinciple, InjectionContext).
+ */
+import type { InjectablePrinciple } from './types.js';
+/**
+ * Generic injection context -- no framework-specific fields.
+ */
+export interface InjectionContext {
+    /** Domain context (e.g., 'coding', 'writing', 'analysis') */
+    domain: string;
+    /** Session identifier */
+    sessionId: string;
+    /** Maximum characters allowed for injected principles */
+    budgetChars: number;
+    /** Principle IDs to exclude from injection (e.g. pruned by audit). Undefined = no masking. */
+    maskedPrincipleIds?: Set<string>;
+}
+/**
+ * Framework-agnostic principle injection interface.
+ *
+ * Wraps the existing budget-aware selection and formatting logic.
+ * Framework adapters convert their context to InjectionContext before calling.
+ */
+export interface PrincipleInjector {
+    /**
+     * Select principles relevant for injection within a character budget.
+     *
+     * @param principles - All available principles to select from
+     * @param context - Generic injection context with budget constraint
+     * @returns Selected principles in injection order
+     */
+    getRelevantPrinciples(principles: InjectablePrinciple[], context: InjectionContext): InjectablePrinciple[];
+    /**
+     * Format a single principle for prompt injection.
+     *
+     * @param principle - The principle to format
+     * @returns Formatted string for prompt injection
+     */
+    formatForInjection(principle: InjectablePrinciple): string;
+}
+/**
+ * Default implementation of PrincipleInjector.
+ *
+ * A minimal framework-agnostic injector using only SDK types.
+ * Selection algorithm:
+ * 1. Separate P0 principles (forced inclusion) from P1/P2
+ * 2. Sort all principles by priority (P0 first), then by createdAt (oldest first)
+ * 3. Include all P0 principles (forced, may exceed budgetChars)
+ * 4. Fill remaining budget with P1/P2 principles in priority order
+ *
+ * Note: P0 forced inclusion may cause total output to exceed budgetChars.
+ * Callers should monitor total formatted length against their budget limit.
+ */
+export declare class DefaultPrincipleInjector implements PrincipleInjector {
+    getRelevantPrinciples(principles: InjectablePrinciple[], context: InjectionContext): InjectablePrinciple[];
+    formatForInjection(principle: InjectablePrinciple): string;
+}
+//# sourceMappingURL=principle-injector.d.ts.map

package/dist/principle-injector.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"principle-injector.d.ts","sourceRoot":"","sources":["../src/principle-injector.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AACH,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,YAAY,CAAC;AAEtD;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B,6DAA6D;IAC7D,MAAM,EAAE,MAAM,CAAC;IACf,yBAAyB;IACzB,SAAS,EAAE,MAAM,CAAC;IAClB,yDAAyD;IACzD,WAAW,EAAE,MAAM,CAAC;IACpB,8FAA8F;IAC9F,kBAAkB,CAAC,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;CAClC;AAED;;;;;GAKG;AACH,MAAM,WAAW,iBAAiB;IAChC;;;;;;OAMG;IACH,qBAAqB,CACnB,UAAU,EAAE,mBAAmB,EAAE,EACjC,OAAO,EAAE,gBAAgB,GACxB,mBAAmB,EAAE,CAAC;IAEzB;;;;;OAKG;IACH,kBAAkB,CAAC,SAAS,EAAE,mBAAmB,GAAG,MAAM,CAAC;CAC5D;AAuBD;;;;;;;;;;;;GAYG;AACH,qBAAa,wBAAyB,YAAW,iBAAiB;IAChE,qBAAqB,CACnB,UAAU,EAAE,mBAAmB,EAAE,EACjC,OAAO,EAAE,gBAAgB,GACxB,mBAAmB,EAAE;IA4DxB,kBAAkB,CAAC,SAAS,EAAE,mBAAmB,GAAG,MAAM;CAG3D"}

package/dist/principle-injector.js

@@ -0,0 +1,89 @@
+/**
+ * Priority order for principle selection.
+ */
+const PRIORITY_ORDER = {
+    'P0': 0,
+    'P1': 1,
+    'P2': 2,
+};
+/**
+ * Parse a priority string to its numeric order value.
+ * @throws Error if priority is unknown (not P0, P1, or P2)
+ */
+function priorityValue(priority) {
+    const p = PRIORITY_ORDER[priority ?? 'P1'];
+    if (p === undefined) {
+        throw new Error(`Unknown principle priority: ${priority}`);
+    }
+    return p;
+}
+/**
+ * Default implementation of PrincipleInjector.
+ *
+ * A minimal framework-agnostic injector using only SDK types.
+ * Selection algorithm:
+ * 1. Separate P0 principles (forced inclusion) from P1/P2
+ * 2. Sort all principles by priority (P0 first), then by createdAt (oldest first)
+ * 3. Include all P0 principles (forced, may exceed budgetChars)
+ * 4. Fill remaining budget with P1/P2 principles in priority order
+ *
+ * Note: P0 forced inclusion may cause total output to exceed budgetChars.
+ * Callers should monitor total formatted length against their budget limit.
+ */
+export class DefaultPrincipleInjector {
+    getRelevantPrinciples(principles, context) {
+        if (!principles || principles.length === 0) {
+            return [];
+        }
+        // Apply masking filter before selection
+        const maskedIds = context.maskedPrincipleIds;
+        const unmasked = maskedIds && maskedIds.size > 0
+            ? principles.filter((p) => !maskedIds.has(p.id))
+            : principles;
+        if (unmasked.length === 0) {
+            return [];
+        }
+        // Separate P0 from P1/P2
+        const p0Principles = unmasked.filter((p) => p.priority === 'P0');
+        const otherPrinciples = unmasked.filter((p) => p.priority !== 'P0');
+        // Pre-parse dates once to avoid repeated Date allocations during sort
+        const p0WithEpoch = p0Principles.map((p) => ({
+            p,
+            epoch: new Date(p.createdAt).getTime(),
+        }));
+        p0WithEpoch.sort((a, b) => a.epoch - b.epoch);
+        const othersWithEpoch = otherPrinciples.map((p) => ({
+            p,
+            priorityVal: priorityValue(p.priority),
+            epoch: new Date(p.createdAt).getTime(),
+        }));
+        othersWithEpoch.sort((a, b) => {
+            if (a.priorityVal !== b.priorityVal)
+                return a.priorityVal - b.priorityVal;
+            return a.epoch - b.epoch;
+        });
+        // Build result: P0 first (forced, may exceed budget), then others
+        const result = [];
+        let usedChars = 0;
+        // ALWAYS include P0 principles (forced inclusion, even if exceeds budget)
+        for (const { p } of p0WithEpoch) {
+            const formatted = this.formatForInjection(p);
+            result.push(p);
+            usedChars += formatted.length;
+        }
+        // Add P1/P2 principles until main budget exhausted
+        for (const { p } of othersWithEpoch) {
+            const formatted = this.formatForInjection(p);
+            if (usedChars + formatted.length <= context.budgetChars) {
+                result.push(p);
+                usedChars += formatted.length;
+            }
+        }
+        return result;
+    }
+    // eslint-disable-next-line @typescript-eslint/class-methods-use-this
+    formatForInjection(principle) {
+        return `- [${principle.id}] ${principle.text}`;
+    }
+}
+//# sourceMappingURL=principle-injector.js.map

package/dist/principle-injector.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"principle-injector.js","sourceRoot":"","sources":["../src/principle-injector.ts"],"names":[],"mappings":"AAwDA;;GAEG;AACH,MAAM,cAAc,GAA2B;IAC7C,IAAI,EAAE,CAAC;IACP,IAAI,EAAE,CAAC;IACP,IAAI,EAAE,CAAC;CACR,CAAC;AAEF;;;GAGG;AACH,SAAS,aAAa,CAAC,QAA4B;IACjD,MAAM,CAAC,GAAG,cAAc,CAAC,QAAQ,IAAI,IAAI,CAAC,CAAC;IAC3C,IAAI,CAAC,KAAK,SAAS,EAAE,CAAC;QACpB,MAAM,IAAI,KAAK,CAAC,+BAA+B,QAAQ,EAAE,CAAC,CAAC;IAC7D,CAAC;IACD,OAAO,CAAC,CAAC;AACX,CAAC;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,OAAO,wBAAwB;IACnC,qBAAqB,CACnB,UAAiC,EACjC,OAAyB;QAEzB,IAAI,CAAC,UAAU,IAAI,UAAU,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YAC3C,OAAO,EAAE,CAAC;QACZ,CAAC;QAED,wCAAwC;QACxC,MAAM,SAAS,GAAG,OAAO,CAAC,kBAAkB,CAAC;QAC7C,MAAM,QAAQ,GAAG,SAAS,IAAI,SAAS,CAAC,IAAI,GAAG,CAAC;YAC9C,CAAC,CAAC,UAAU,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,SAAS,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC;YAChD,CAAC,CAAC,UAAU,CAAC;QAEf,IAAI,QAAQ,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YAC1B,OAAO,EAAE,CAAC;QACZ,CAAC;QAED,yBAAyB;QACzB,MAAM,YAAY,GAAG,QAAQ,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,QAAQ,KAAK,IAAI,CAAC,CAAC;QACjE,MAAM,eAAe,GAAG,QAAQ,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,QAAQ,KAAK,IAAI,CAAC,CAAC;QAEpE,sEAAsE;QACtE,MAAM,WAAW,GAAG,YAAY,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;YAC3C,CAAC;YACD,KAAK,EAAE,IAAI,IAAI,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,OAAO,EAAE;SACvC,CAAC,CAAC,CAAC;QACJ,WAAW,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,KAAK,GAAG,CAAC,CAAC,KAAK,CAAC,CAAC;QAE9C,MAAM,eAAe,GAAG,eAAe,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;YAClD,CAAC;YACD,WAAW,EAAE,aAAa,CAAC,CAAC,CAAC,QAAQ,CAAC;YACtC,KAAK,EAAE,IAAI,IAAI,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,OAAO,EAAE;SACvC,CAAC,CAAC,CAAC;QACJ,eAAe,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE;YAC5B,IAAI,CAAC,CAAC,WAAW,KAAK,CAAC,CAAC,WAAW;gBAAE,OAAO,CAAC,CAAC,WAAW,GAAG,CAAC,CAAC,WAAW,CAAC;YAC1E,OAAO,CAAC,CAAC,KAAK,GAAG,CAAC,CAAC,KAAK,CAAC;QAC3B,CAAC,CAAC,CAAC;QAEH,kEAAkE;QAClE,MAAM,MAAM,GAA0B,EAAE,CAAC;QACzC,IAAI,SAAS,GAAG,CAAC,CAAC;QAElB,0EAA0E;QAC1E,KAAK,MAAM,EAAE,CAAC,EAAE,IAAI,WAAW,EAAE,CAAC;YAChC,MAAM,SAAS,GAAG,IAAI,CAAC,kBAAkB,CAAC,CAAC,CAAC,CAAC;YAC7C,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;YACf,SAAS,IAAI,SAAS,CAAC,MAAM,CAAC;QAChC,CAAC;QAED,mDAAmD;QACnD,KAAK,MAAM,EAAE,CAAC,EAAE,IAAI,eAAe,EAAE,CAAC;YACpC,MAAM,SAAS,GAAG,IAAI,CAAC,kBAAkB,CAAC,CAAC,CAAC,CAAC;YAC7C,IAAI,SAAS,GAAG,SAAS,CAAC,MAAM,IAAI,OAAO,CAAC,WAAW,EAAE,CAAC;gBACxD,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;gBACf,SAAS,IAAI,SAAS,CAAC,MAAM,CAAC;YAChC,CAAC;QACH,CAAC;QAED,OAAO,MAAM,CAAC;IAChB,CAAC;IAED,qEAAqE;IACrE,kBAAkB,CAAC,SAA8B;QAC/C,OAAO,MAAM,SAAS,CAAC,EAAE,KAAK,SAAS,CAAC,IAAI,EAAE,CAAC;IACjD,CAAC;CACF"}