@maolon/pi-watcher 0.0.0-stage → 0.1.1

package/dist/contracts/relay-next.interfaces.d.ts

@@ -0,0 +1,160 @@
+/**
+ * Watcher-side view of the pi-relay managed-delivery shapes (receipts, withdraw results,
+ * consumer responses). pi-relay does not re-export these types from its public entry points,
+ * so they are declared here; keep them in sync with the @maolon/pi-relay version in package.json.
+ */
+export type Json = null | boolean | number | string | Json[] | {
+    [key: string]: Json;
+};
+export interface Event {
+    kind: 'event';
+    id: string;
+    type: string;
+    schemaVersion: number;
+    subject?: string;
+    occurredAt: string;
+    validUntil: string;
+    data: {
+        [key: string]: Json;
+    };
+}
+export interface Scope {
+    id: string;
+    revision: number;
+}
+export interface ManagedOptions {
+    audienceRef: string;
+    scope: Scope;
+    consumerProfileId: string;
+    requestedMode: 'display' | 'resume';
+}
+export interface RouteReceipt {
+    routeRef: string;
+    targetRevision: number;
+    targetUpdatedAt?: string;
+    freshness: 'fresh' | 'stale' | 'offline';
+    admission: 'accepted' | 'staged' | 'rejected' | 'unknown';
+    delivery: 'pending' | 'held' | 'intent' | 'submitted' | 'recorded' | 'unknown' | 'suppressed' | 'expired' | 'withdrawn';
+    withdrawal: 'none' | 'pending' | 'prevented' | 'too_late' | 'unknown';
+}
+export interface ApplicationResult {
+    outcome: 'applied' | 'stale' | 'rejected';
+    applicationRevision: number;
+    code: 'APPLIED' | 'STALE_EPISODE' | 'OWNER_MISMATCH' | 'ALREADY_CLOSED' | 'INVALID_RESPONSE';
+}
+export interface ConsumerResponse {
+    responseId: string;
+    deliveryRef: string;
+    responseType: string;
+    schemaVersion: number;
+    data: {
+        [key: string]: Json;
+    };
+    createdAt: string;
+    state: 'target_staged' | 'source_recorded' | 'application_applied';
+    applicationResult?: ApplicationResult;
+}
+export interface ManagedReceipt {
+    eventId: string;
+    sourceState: 'captured' | 'empty_audience' | 'rejected' | 'unknown';
+    sourceCursor: number;
+    scope: Scope;
+    routes: RouteReceipt[];
+    responses: ConsumerResponse[];
+}
+export interface WithdrawResult {
+    operationId: string;
+    eventId: string;
+    sourceApplied: boolean;
+    routes: Array<{
+        routeRef: string;
+        disposition: 'prevented' | 'too_late' | 'pending' | 'unknown';
+    }>;
+}
+export interface ScopeAdvance {
+    operationId: string;
+    scopeId: string;
+    expectedRevision: number;
+    nextRevision: number;
+    state: 'active' | 'paused' | 'closed';
+}
+export interface ManagedSource {
+    publishManaged(event: Event, options: ManagedOptions): Promise<ManagedReceipt>;
+    getManagedReceipt(eventId: string): Promise<ManagedReceipt>;
+    watchManagedUpdates(after: number, limit: number): Promise<{
+        cursor: number;
+        resyncRequired: boolean;
+        updates: ManagedReceipt[];
+    }>;
+    withdraw(operationId: string, eventId: string, reason: string): Promise<WithdrawResult>;
+    advanceScope(input: ScopeAdvance): Promise<{
+        revision: number;
+        state: 'active' | 'paused' | 'closed';
+        pendingRouteControls: number;
+    }>;
+    confirmApplied(operationId: string, responseId: string, result: ApplicationResult): Promise<void>;
+    dispose(): void;
+}
+export interface GateResult {
+    decision: 'allow' | 'defer' | 'drop';
+    reasonCode: 'CURRENT' | 'BUSY' | 'SOURCE_UNAVAILABLE' | 'GUARD_UNAVAILABLE' | 'STALE_REQUEST' | 'CANCELLED' | 'WRONG_OWNER' | 'EXPIRED';
+    guardEpoch: number;
+    validUntil?: string;
+}
+export interface ConsumerContext {
+    readonly deliveryRef: string;
+    readonly bindingEpoch: number;
+    readonly profileId: string;
+}
+export interface ConsumerRegistration {
+    profileId: string;
+    eventManifestDigest: string;
+    responseManifestDigest: string;
+    guardImplementationId: string;
+    timeoutMs: number;
+}
+export interface ConsumerAPI {
+    registerConsumer(profile: ConsumerRegistration, assess: (event: Event, context: ConsumerContext, signal: AbortSignal) => Promise<GateResult>): () => void;
+    respond(input: {
+        operationId: string;
+        deliveryRef: string;
+        responseType: string;
+        schemaVersion: number;
+        data: {
+            [key: string]: Json;
+        };
+    }): Promise<{
+        responseId: string;
+        state: 'target_staged' | 'source_recorded' | 'application_applied';
+        applicationResult?: ApplicationResult;
+    }>;
+}
+export interface SetupPlan {
+    sourceRef: string;
+    channelId: string;
+    consumerProfileId: string;
+    audienceIntent: 'single-current-owner';
+    requestedMode: 'display' | 'resume';
+    grant: {
+        maxClaims: number;
+        ttlMs: number;
+        eventTypes: string[];
+    };
+}
+export interface OwnerAPI {
+    prepareSetup(plan: SetupPlan): Promise<{
+        operationId: string;
+        planDigest: string;
+        ownerPrompt: string;
+    }>;
+    /** consentReceiptRef comes from trusted owner UI, never from an LLM boolean. */
+    commitSetup(input: {
+        operationId: string;
+        planDigest: string;
+        consentReceiptRef: string;
+    }): Promise<{
+        state: 'complete' | 'partial';
+        audienceRef?: string;
+        receipts: Json[];
+    }>;
+}

package/dist/contracts/relay-next.interfaces.js

@@ -0,0 +1 @@
+export {};

package/dist/engine/cards.d.ts

@@ -0,0 +1,68 @@
+/**
+ * Result card (design 6.6): deterministic template built from verified structured facts.
+ * Unknown fields are explicitly unknown; a zero exit code does not mean tests/business passed (I14).
+ */
+import type { WatchSpec } from '../contracts/interfaces.js';
+import type { WatchSnapshot } from '../storage/store.js';
+export interface ResultCard {
+    schemaVersion: 1;
+    resultId: string;
+    watchId: string;
+    generation: number;
+    target: WatchSpec['target'];
+    executorState: string;
+    checks: Array<{
+        checkId: string;
+        outcome: string;
+        artifactDigest: string | null;
+    }>;
+    artifactIds: string[];
+    businessAcceptance: string;
+    health: string;
+    observedAt: string;
+    summary: string;
+    /** display-only declaration: local display copy, not a relay delivery fact */
+    deliveryNote?: string;
+}
+export declare function buildResultCard(input: {
+    resultId: string;
+    spec: WatchSpec;
+    snapshot: WatchSnapshot;
+    requiredCheckIds: readonly string[];
+    health: string;
+    observedAtMs: number;
+    deliveryNote?: string;
+}): ResultCard;
+export interface GroupResultCard {
+    schemaVersion: 1;
+    resultId: string;
+    watchId: string;
+    generation: number;
+    target: WatchSpec['target'];
+    kind: 'group-summary';
+    readyWhen: string;
+    members: Array<{
+        watchId: string;
+        taskState: string;
+        lifecycle: string;
+    }>;
+    overall: 'all-succeeded' | 'all-terminal-with-failures' | 'partial';
+    health: string;
+    observedAt: string;
+    summary: string;
+    deliveryNote?: string;
+}
+/** V3 group result card: member projection summary; no member-level acceptance judgment (each member's own card is responsible). */
+export declare function buildGroupResultCard(input: {
+    resultId: string;
+    spec: WatchSpec;
+    members: Array<{
+        watchId: string;
+        taskState: string;
+        lifecycle: string;
+    }>;
+    readyWhen: 'all_terminal' | 'all_succeeded';
+    health: string;
+    observedAtMs: number;
+    deliveryNote?: string;
+}): GroupResultCard;

package/dist/engine/cards.js

@@ -0,0 +1,76 @@
+/**
+ * Result card (design 6.6): deterministic template built from verified structured facts.
+ * Unknown fields are explicitly unknown; a zero exit code does not mean tests/business passed (I14).
+ */
+import { completionLevel } from './hard-rules.js';
+export function buildResultCard(input) {
+    const { resultId, spec, snapshot, requiredCheckIds, health, observedAtMs, deliveryNote } = input;
+    const completion = completionLevel(spec, snapshot, requiredCheckIds);
+    const summaryLines = [];
+    switch (completion.overall) {
+        case 'succeeded-evidence':
+            summaryLines.push('Succeeded; required checks passed and required artifacts present (verified tier).');
+            break;
+        case 'failed':
+            summaryLines.push(`Failed (exitCode=${snapshot.exitCode ?? 'unknown'}); root cause may still be unknown.`);
+            break;
+        case 'cancelled':
+            summaryLines.push('Execution was cancelled.');
+            break;
+        case 'incomplete-evidence':
+            summaryLines.push('Reported terminal but completion evidence is incomplete (missing checks or artifacts).');
+            break;
+        case 'in-progress':
+            summaryLines.push(`Still running (state=${snapshot.taskState}).`);
+            break;
+    }
+    if (completion.businessAcceptance === 'pending_host') {
+        summaryLines.push('Business acceptance pending host (pending_host).');
+    }
+    const card = {
+        schemaVersion: 1,
+        resultId,
+        watchId: spec.watchId,
+        generation: spec.generation,
+        target: spec.target,
+        executorState: completion.executorState,
+        checks: completion.checks,
+        artifactIds: snapshot.artifactIds ?? [],
+        businessAcceptance: completion.businessAcceptance,
+        health,
+        observedAt: new Date(observedAtMs).toISOString(),
+        summary: summaryLines.join(' ')
+    };
+    if (deliveryNote) {
+        card.deliveryNote = deliveryNote;
+    }
+    return card;
+}
+/** V3 group result card: member projection summary; no member-level acceptance judgment (each member's own card is responsible). */
+export function buildGroupResultCard(input) {
+    const { resultId, spec, members, readyWhen, health, observedAtMs, deliveryNote } = input;
+    const succeeded = members.filter(m => m.taskState === 'succeeded').length;
+    const terminal = members.filter(m => ['succeeded', 'failed', 'cancelled'].includes(m.taskState)).length;
+    const overall = members.length > 0 && succeeded === members.length
+        ? 'all-succeeded'
+        : members.length > 0 && terminal === members.length
+            ? 'all-terminal-with-failures'
+            : 'partial';
+    const card = {
+        schemaVersion: 1,
+        resultId,
+        watchId: spec.watchId,
+        generation: spec.generation,
+        target: spec.target,
+        kind: 'group-summary',
+        readyWhen,
+        members,
+        overall,
+        health,
+        observedAt: new Date(observedAtMs).toISOString(),
+        summary: `group ${readyWhen}: ${terminal}/${members.length} terminal, ${succeeded}/${members.length} succeeded`
+    };
+    if (deliveryNote)
+        card.deliveryNote = deliveryNote;
+    return card;
+}

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;
+};