@maolon/pi-watcher 0.0.0-stage → 0.1.0

package/dist/engine/engine.d.ts

@@ -0,0 +1,178 @@
+/**
+ * WatchEngine: inspection pipeline (deterministic V1 subset of the design 5.2 processing order).
+ * 1) validate active/validity -> 2) read events/state (T2 ingest) -> 3) hard rules
+ * -> 4) episode supersede + result card (durable outbox + local display copy).
+ * The Jev semantic layer is wired in at V2 (JudgePort is ready); V1 has deterministic facts only.
+ */
+import type { Observation, SourceAdapter, Probe, JudgePort, ManagedDeliveryPort } from '../contracts/interfaces.js';
+import type { WatchStore, WatchRow, WatchSnapshot } from '../storage/store.js';
+import type { Clock } from '../util/clock.js';
+import { type SemanticThresholds } from './semantic.js';
+export interface WatchEngineOptions {
+    clock: Clock;
+    store: WatchStore;
+    adapters: Map<string, SourceAdapter>;
+    requiredCheckIds?: ReadonlyMap<string, readonly string[]>;
+    /** V2 hook: shadow/active semantic judgment; may be omitted in V1 */
+    judge?: JudgePort;
+    /** Note for the local display copy of the result card */
+    displayNote?: string;
+    /** V2 semantic-layer config (defaults to policy-defaults) */
+    semantic?: SemanticEngineConfig;
+    /** Data egress consent (required for live Jev; Mock does not export locally, tests may set judgeRequiresConsent=false) */
+    semanticConsent?: boolean | (() => boolean);
+    /** Whether the judge is egress-type (needs consent); pass false for Mock local judgment */
+    judgeRequiresConsent?: boolean;
+    /** V1 closed loop: relay managed delivery port (static or live reference; upgraded after mid-session bind) */
+    delivery?: ManagedDeliveryPort | (() => ManagedDeliveryPort | undefined);
+    /** Notification hook after attention lands in the outbox (for the display layer; does not block the engine) */
+    onAttention?: (notice: AttentionNotice) => void;
+    /** Judgment-complete notice (display layer; fires after an accepted judgment, must not block the engine) */
+    onJudgment?: (notice: JudgmentNotice) => void;
+}
+/** Attention notification published by the engine (passed across layers to the display layer / session toast). */
+export interface AttentionNotice {
+    watchId: string;
+    ownerSession?: string;
+    episodeId: string;
+    reasonCode: string;
+    summary: string;
+    transport: 'relay-managed' | 'local-display' | 'relay-failed';
+    /** Failure reason when transport=relay-failed (same source as outbox admission_json.error) */
+    relayError?: string;
+    /** Deadline until which the envelope is still valid (ms epoch) */
+    validUntil: number;
+}
+/** Accepted-judgment-complete notification (display-layer notice; judge review must be visible) */
+export interface JudgmentNotice {
+    watchId: string;
+    ownerSession?: string;
+    objective: string;
+    /** shadow = record only; active = may create episode/attention */
+    mode: 'shadow' | 'active';
+    /** Candidates that hit the threshold (none -> everything normal, no action needed) */
+    candidates: Array<{
+        reason: string;
+        probability: number;
+        note: string | null;
+    }>;
+    probabilities: Record<string, number>;
+}
+export interface SemanticEngineConfig {
+    thresholds: SemanticThresholds;
+    maxJudgeRequestsPerRootDay: number;
+    maxProbesPerInspection: number;
+    maxProbesPerEpisode: number;
+    maxEvidenceEvents: number;
+    stateMaxBytes: number;
+}
+export declare const DEFAULT_SEMANTIC_CONFIG: SemanticEngineConfig;
+/** Default attention envelope validity: real wake latency includes safety-net ticks / long turns,
+ *  300s is not enough; also bounds the fast-close line. */
+export declare const DEFAULT_ATTENTION_TTL_MS = 1800000;
+export interface InspectionOutcome {
+    inspectionId: string;
+    watchId: string;
+    ingested: number;
+    produced: {
+        episodes: string[];
+        resultCards: string[];
+    };
+    health: WatchRow['health'];
+    lifecycleAfter: WatchRow['lifecycle'];
+}
+export declare class WatchEngine {
+    private readonly clock;
+    private readonly store;
+    private readonly adapters;
+    private readonly requiredCheckIds;
+    private readonly judge?;
+    private readonly displayNote;
+    private readonly semanticConfig;
+    private readonly semanticConsentRef;
+    private readonly judgeRequiresConsent;
+    private readonly deliveryRef;
+    private readonly onAttention?;
+    private readonly onJudgment?;
+    /** Single-flight per Watch (design 5.6) */
+    private readonly semanticInFlight;
+    /** After 401/403, egress is disabled within this process (design 5.6) */
+    private judgeDisabled;
+    constructor(options: WatchEngineOptions);
+    /** Consent is read live: the user may grant or revoke it mid-session (/watcher jev consent). */
+    private get semanticConsent();
+    private get delivery();
+    /** Run due inspections: returns the list of executed inspectionIds. */
+    runDue(limit?: number): Promise<string[]>;
+    inspectWatch(watchId: string, signal?: AbortSignal): Promise<InspectionOutcome | null>;
+    /**
+     * V2 semantic inspection (design 5.2 steps 3-5 / 5.5 / 5.6).
+     * Network calls do not hold a SQL write transaction; single-flight per Watch; late results are discarded after version check.
+     */
+    private runSemanticPass;
+    /** V3: group (design 3.x watch-group) -- reads committed child Watch state. */
+    private inspectGroup;
+    /** V3: explicit follow-up obligation (pi-obligation-v1 semantics; pure time reminder = obligation without dependencies). */
+    private inspectObligation;
+    /** Unified attention publishing for hard facts / semantic candidates: truth lands in the outbox first, then publishes via relay managed delivery (I6). */
+    private publishEpisodeAttention;
+    /**
+     * Publishes an attention through the relay managed path; only advances admission, never the
+     * frozen truth (I06). The scope used is recorded in admission_json so a retry re-sends the
+     * identical (event, options) pair. Never throws: returns status for loud failure handling.
+     */
+    private publishAttention;
+    /** Records that an attention could not be published yet (scope control unconfirmed). */
+    private deferAttention;
+    /**
+     * Returns the watch's relay scope, creating it on first use (expectedRevision=0 ->
+     * nextRevision=1, design 9.6). Unconfirmed control ops for the watch are drained first;
+     * if any remain open, or the scope is not active, publishing is blocked (design 7.7).
+     * scopeId = scope-<watchId>-g<generation>-e<bindingEpoch>: a generation or owner-binding
+     * change yields a new scope, and the old one is never reused.
+     */
+    private ensureRelayScope;
+    /**
+     * Drains the durable control outbox (design 7.3 T6 / 7.7): scope advances FIFO per watch,
+     * then pending event withdraws. Each op is retried under its original operationId; the
+     * relay dedupes by operationId + request digest. Deterministic relay refusals are recorded
+     * as rejected (no retry); anything else stays unknown and is retried on the next sweep.
+     */
+    drainControl(watchId?: string): Promise<void>;
+    /**
+     * Delivery health: for attentions that are unknown (publish failed)
+     * or deferred (scope control unconfirmed) while the episode is still open, each sweep
+     * (a) retries once if the envelope is still valid, re-sending the same (event, options);
+     * (b) otherwise only reports loudly (the host must inspect).
+     * Withdrawn events are never re-published; an event whose recorded scope has since
+     * advanced is fenced and marked rejected instead of being re-sent under a new scope.
+     */
+    private checkDeliveryHealth;
+    /** Terminal-state watch auto-close: supersede open episodes -> superseded, lifecycle -> closed (does not touch controlRevision CAS semantics). */
+    private autoCloseTerminal;
+    private degrade;
+    /**
+     * Delivery guard: there is a wake the host never confirmed -- episode still open and its
+     * attention admission is in {unknown, pending, publishing} (publish unconfirmed) or =source-staged
+     * and the envelope has not expired (relay delivery in flight) -> returns true, blocking ttlElapsed auto-close.
+     */
+    private hasUndeliveredWake;
+    /** slot = (watchId, generation, kind, checkpointId); at most one active episode per slot (design 3.3). */
+    private openEpisode;
+    private ensureMonitorEpisode;
+    /** Result card: truth = durable outbox (I6: event bytes/ID/expiry frozen); the display copy is persisted separately (I16). */
+    private commitResultCard;
+    /** probes delegation (trusted candidates, design 4.4) */
+    listProbes(watchId: string): Promise<readonly Probe[]>;
+    executeProbe(watchId: string, probeId: string, signal?: AbortSignal): Promise<Observation[]>;
+}
+/**
+ * Projects one identity-checked observation onto the snapshot. Shared by ingest and probe
+ * ingestion so both paths derive the same state from the same evidence. activityAtMs is set
+ * when the observation counts as task activity (status/heartbeat/log_delta) for the silence
+ * rule; validation/artifact observations do not.
+ */
+export declare function applyObservationToSnapshot(snapshot: WatchSnapshot, obs: Observation, now: number): {
+    snapshot: WatchSnapshot;
+    activityAtMs: number | null;
+};