@principles/host-runtime 0.1.0 → 0.2.0

package/dist/active-principle-prompt.js

@@ -16,6 +16,10 @@ export async function buildActivePrinciplePromptContext(input) {
         warnings.push('prompt_feature_disabled; nextAction=set features.prompt.enabled=true in .pd/config.yaml');
         return { additionalContext: '', principleIds: [], activationIds: [], artifactIds: [], warnings, budget: RUNTIME_V2_PRINCIPLE_BUDGET, truncated: false, excludedPrincipleIds, excludedCount: 0, allValidatedPrinciplesExcluded: false };
     }
+    // PRI-532: agent self-report instruction rides the directive template when
+    // the flag is on (flag-off keeps the template byte-identical).
+    const selfReportEnabled = computeFeatureFlagsFromConfig(config.effective)
+        .flags.principle_receipt_self_report?.enabled === true;
     let connection;
     const stateDbPath = path.join(input.workspaceDir, '.pd', 'state.db');
     if (!fs.existsSync(stateDbPath)) {
@@ -74,7 +78,7 @@ export async function buildActivePrinciplePromptContext(input) {
     let truncated = false;
     for (const principle of principles) {
         const candidate = [...included, principle];
-        const candidateContext = renderPrinciplesToDirectives(candidate, new Set(candidate.map((entry) => entry.principleId)), escapeXml);
+        const candidateContext = renderPrinciplesToDirectives(candidate, new Set(candidate.map((entry) => entry.principleId)), { escapeFn: escapeXml, selfReportInstruction: selfReportEnabled });
         if (candidateContext.length > RUNTIME_V2_PRINCIPLE_BUDGET) {
             truncated = true;
             break;

package/dist/governance-observation-store.d.ts

@@ -0,0 +1,196 @@
+import Database from 'better-sqlite3';
+export declare const GOVERNANCE_RETENTION_MAX_TURNS = 32;
+export declare const GOVERNANCE_RETENTION_MAX_AGE_MS: number;
+export declare const GOVERNANCE_PROMOTION_PRECEDING_TURNS = 12;
+export declare const GOVERNANCE_PENDING_TAIL_STALE_MS: number;
+export type GovernanceObservationKind = 'user_turn' | 'assistant_turn' | 'tool_call';
+export type GovernanceObservationSource = 'live_hook' | 'transcript';
+export type GovernanceObservationCompleteness = 'complete' | 'partial';
+export type GovernanceRetentionClass = 'operational' | 'promoted' | 'expired' | 'rolled_back';
+export interface GovernanceObservationInput {
+    readonly hostKind: 'codex';
+    readonly rolloutIdentity: string;
+    readonly rootSessionId: string;
+    readonly parentRolloutIdentity?: string;
+    readonly agentIdentity?: string;
+    readonly agentDepth?: number;
+    readonly hostTurnId: string;
+    readonly kind: GovernanceObservationKind;
+    /** Semantic convergence identity (SPEC §6). Built by the host adapter. */
+    readonly logicalObservationKey: string;
+    /** Physical replay identity: `host|rollout|ordinal` (SPEC §6). */
+    readonly transcriptRecordKey?: string;
+    /**
+     * Byte offset of the source record start — the durable transcript SOURCE
+     * ORDER (records are append-only, so byte position is strictly increasing
+     * within one rollout). All before/after/last-N/next-assistant logic orders
+     * by this value, never by the SQLite insertion id: a live hook row is
+     * inserted BEFORE the older history that a later catch-up ingests, so
+     * insertion order is not transcript order (PR #1455 review P1).
+     */
+    readonly recordByteStart?: number;
+    /** Per-rollout physical record ordinal (G1 §4) — tiebreaker/telemetry alongside the byte order. */
+    readonly recordOrdinal?: number;
+    readonly assistantItemId?: string;
+    /** assistant phase: 'commentary' | 'final_answer' (assistant_turn only). */
+    readonly phase?: string;
+    readonly toolUseId?: string;
+    /** Transcript model-level call id (call_*) — different id space than toolUseId. */
+    readonly transcriptToolCallId?: string;
+    readonly visibleText?: string;
+    readonly toolFacts?: unknown;
+    readonly source: GovernanceObservationSource;
+    readonly completeness: GovernanceObservationCompleteness;
+    readonly observedAt: string;
+}
+export interface GovernanceCheckpointInput {
+    readonly hostKind: 'codex';
+    readonly rolloutIdentity: string;
+    readonly byteOffset: number;
+    readonly lastOrdinal: number;
+    readonly cliVersion?: string;
+    readonly rootSessionId: string;
+    readonly incompleteTail: boolean;
+}
+export interface GovernanceIngestDegradation {
+    readonly reason: string;
+    readonly ordinal?: number;
+    readonly nextAction?: string;
+}
+export interface IngestGovernanceObservationsResult {
+    readonly ok: boolean;
+    readonly reason?: string;
+    readonly nextAction?: string;
+    readonly inserted: number;
+    readonly enriched: number;
+    readonly duplicates: number;
+    readonly checkpointCommitted: boolean;
+    readonly warnings: readonly string[];
+}
+export interface GovernanceCheckpointRecord {
+    readonly hostKind: string;
+    readonly rolloutIdentity: string;
+    readonly byteOffset: number;
+    readonly lastOrdinal: number;
+    readonly cliVersion: string | null;
+    readonly rootSessionId: string;
+    readonly incompleteTail: boolean;
+    readonly lastDegradationReason: string | null;
+    readonly lastDegradationOrdinal: number | null;
+    readonly updatedAt: string;
+}
+export interface GovernanceObservationRecord {
+    readonly id: number;
+    readonly rolloutIdentity: string;
+    readonly rootSessionId: string;
+    readonly hostTurnId: string;
+    readonly kind: GovernanceObservationKind;
+    readonly logicalKey: string;
+    readonly transcriptRecordKey: string | null;
+    readonly sourceOrder: number | null;
+    readonly sourceOrdinal: number | null;
+    readonly assistantItemId: string | null;
+    readonly phase: string | null;
+    readonly toolUseId: string | null;
+    readonly transcriptToolCallId: string | null;
+    readonly visibleText: string | null;
+    readonly sanitizedToolFactsJson: string | null;
+    readonly source: GovernanceObservationSource;
+    readonly completeness: GovernanceObservationCompleteness;
+    readonly retentionClass: GovernanceRetentionClass;
+    readonly observedAt: string;
+    readonly promotionRef: string | null;
+}
+export interface PromoteGovernanceEvidenceInput {
+    readonly workspaceDir: string;
+    readonly hostKind: 'codex';
+    readonly rolloutIdentity: string;
+    readonly triggerLogicalKey: string;
+    /** Caller-provided pain reference. Slice A never mints a pain identity (SPEC §18). */
+    readonly painRef: string;
+    readonly now?: Date;
+    readonly databaseFactory?: ObservationDatabaseFactory;
+}
+export type PromoteGovernanceEvidenceResult = {
+    ok: true;
+    promoted: number;
+    tailState: 'completed' | 'pending';
+    warnings: readonly string[];
+} | {
+    ok: false;
+    reason: string;
+    nextAction: string;
+};
+export type ObservationDatabaseFactory = (databasePath: string) => Database.Database;
+/**
+ * Shared with the sibling governance-signal-admission module (Slice B): both
+ * modules own separate governance_* tables in the same trajectory.db, and the
+ * admission/reconciliation paths read observation-owned tables (promotion
+ * tails). One open must make the whole governance schema ready.
+ */
+export declare function ensureGovernanceSchema(db: Database.Database): void;
+type Degradation = {
+    ok: false;
+    reason: string;
+    nextAction: string;
+};
+export interface GovernanceRolloutDescriptor {
+    readonly hostKind: 'codex';
+    readonly rolloutIdentity: string;
+    readonly rootSessionId: string;
+    readonly parentRolloutIdentity?: string;
+    readonly agentIdentity?: string;
+    readonly agentDepth?: number;
+}
+export interface IngestGovernanceObservationsInput {
+    readonly workspaceDir: string;
+    /** Rollout lineage, established even when a delta contains no projected observations (markers/skips only). */
+    readonly rollout?: GovernanceRolloutDescriptor;
+    readonly observations: readonly GovernanceObservationInput[];
+    readonly checkpoint?: GovernanceCheckpointInput;
+    readonly degradations?: readonly GovernanceIngestDegradation[];
+    readonly compactionTimestamp?: string;
+    /** Sequential rollback markers (num_turns each) decoded from the transcript delta. */
+    readonly rollbackTurns?: readonly number[];
+    readonly now?: Date;
+    readonly databaseFactory?: ObservationDatabaseFactory;
+}
+export declare function ingestGovernanceObservations(input: IngestGovernanceObservationsInput): IngestGovernanceObservationsResult;
+export interface ReadGovernanceCheckpointArgs {
+    readonly workspaceDir: string;
+    readonly hostKind: 'codex';
+    readonly rolloutIdentity: string;
+    readonly databaseFactory?: ObservationDatabaseFactory;
+}
+export declare function readGovernanceCheckpoint(args: ReadGovernanceCheckpointArgs): GovernanceCheckpointRecord | null | Degradation;
+export interface ListGovernanceCheckpointsArgs {
+    readonly workspaceDir: string;
+    readonly hostKind: 'codex';
+    readonly databaseFactory?: ObservationDatabaseFactory;
+}
+export type ListGovernanceCheckpointsResult = {
+    ok: true;
+    checkpoints: readonly GovernanceCheckpointRecord[];
+} | Degradation;
+/**
+ * List every checkpoint for a host kind, oldest-updated first (PRI-624).
+ * The Slice C worker/CLI catch-up uses this to find rollouts with pending
+ * transcript lag — the checkpoint set is exactly the set of rollouts the
+ * authenticated hook previously delivered, so this is never session
+ * discovery (SPEC §13 / ADR-0020 §11.2).
+ */
+export declare function listGovernanceCheckpoints(args: ListGovernanceCheckpointsArgs): ListGovernanceCheckpointsResult;
+export interface ListGovernanceObservationsInput {
+    readonly workspaceDir: string;
+    readonly rolloutIdentity?: string;
+    readonly retentionClass?: GovernanceRetentionClass;
+    readonly limit?: number;
+    readonly databaseFactory?: ObservationDatabaseFactory;
+}
+export type ListGovernanceObservationsResult = {
+    ok: true;
+    observations: readonly GovernanceObservationRecord[];
+} | Degradation;
+export declare function listGovernanceObservations(input: ListGovernanceObservationsInput): ListGovernanceObservationsResult;
+export declare function promoteGovernanceEvidence(input: PromoteGovernanceEvidenceInput): PromoteGovernanceEvidenceResult;
+export {};