@maolon/pi-watcher 0.0.0-stage → 0.1.0

package/dist/contracts/interfaces.d.ts

@@ -0,0 +1,262 @@
+/** pi-watcher core ports and domain types (engine, store, sources, judge, managed delivery). */
+export type Id = string;
+export type Json = null | boolean | number | string | Json[] | {
+    [key: string]: Json;
+};
+export type SemanticMode = 'off' | 'shadow' | 'active';
+export type RunTarget = {
+    kind: 'run';
+    sourceId: Id;
+    taskId: Id;
+    runId: Id;
+    attemptId: Id; /**
+     * decision-delta 2026-09-21 (universal monitor mode, not in design package v0.2.0):
+     * agent-declared
+     * generic evidence sources. The typed source enum is removed as a product surface (unified-exec deleted);
+     * agent-file / agent-check are the only two agent registration surfaces.
+     *
+     * file: tail a declared file path; an okPattern/failPattern hit in the tail window is the only
+     * content terminal-state evidence (fail takes precedence over ok); growth means progress; file missing/rotated -> degraded, non-terminal;
+     * having no fd holder is not exit evidence (a writer may open the file per write).
+     */
+    file?: {
+        path: string;
+        okPattern?: string;
+        failPattern?: string;
+    }; /**
+    * check: an agent-declared bounded check command. The watcher runs cmd at a fixed cadence (within timeoutMs,
+    * SIGTERM->SIGKILL); a non-zero exit code has three meanings, mapped by the declaration: exit 0 / okPattern ->
+    * succeeded; failCodes / failPattern -> failed; 126/127/timeout/spawn error ->
+    * unknown+degraded (the check is broken; do not sentence the task to death); any other non-zero -> running (pending).
+    * The original cmd text is stored with the spec as evidence -- it must not contain secrets.
+    */
+    check?: {
+        cmd: string;
+        cwd?: string;
+        timeoutMs?: number;
+        okPattern?: string;
+        failPattern?: string;
+        failCodes?: number[];
+    };
+};
+export type ChildRef = {
+    watchId: Id;
+    generation: number;
+};
+export type Target = RunTarget | {
+    kind: 'group';
+    members: ChildRef[];
+    readyWhen: 'all_terminal' | 'all_succeeded';
+} | {
+    kind: 'obligation';
+    dependencies: ChildRef[];
+    readyWhen: 'all_terminal' | 'all_succeeded';
+    hostAction: string;
+};
+export type Owner = {
+    sessionId: Id;
+    originAnchor: string | null;
+    bindingEpoch: number;
+    profileId: Id;
+};
+export interface WatchSpec {
+    schemaVersion: 1;
+    watchId: Id;
+    generation: number;
+    missionRevision: number;
+    controlRevision: number;
+    mode: 'embedded' | 'service';
+    owner: Owner;
+    target: Target;
+    mission: {
+        objective: string;
+        scope: string;
+        checkpointId: Id;
+        requiredArtifacts: Id[];
+        requiresChecks: boolean;
+        businessAcceptance: 'host' | 'not_required';
+        deadlineAt?: string;
+    };
+    policy: {
+        transport: 'local-display' | 'relay';
+        semanticMode: SemanticMode;
+        notificationOwner: 'watcher' | 'external';
+        requestKinds: string[];
+        maxRequestsPerEpisode: number;
+        episodeCooldownMs: number;
+        attentionTtlMs: number;
+    };
+    limits: {
+        pollMinMs: number;
+        pollMaxMs: number;
+        maxSilenceMs: number;
+        maxProbesPerEpisode: number;
+        maxJudgeRequestsPerDay: number;
+        expiresAt: string;
+    };
+}
+export type RegisterCandidate = Omit<WatchSpec, 'watchId' | 'generation' | 'missionRevision' | 'controlRevision' | 'owner'>;
+export interface ActorContext {
+    actorId: Id;
+    owner: Owner;
+    profileRevision: number;
+    permitted: ReadonlySet<string>;
+}
+export interface Basis {
+    watchId: Id;
+    generation: number;
+    missionRevision: number;
+    controlRevision: number;
+    observationSeq: number;
+    windowDigest: string;
+}
+export interface EvidenceRef {
+    evidenceId: Id;
+    sourceId: Id;
+    capturedAt: string;
+    sha256: string;
+    bytes: number;
+    sampled: boolean;
+}
+export interface Observation {
+    schemaVersion: 1;
+    observationId: Id;
+    target: RunTarget;
+    sourceSeq: number;
+    observedAt: string;
+    kind: 'status' | 'heartbeat' | 'log_delta' | 'validation' | 'artifact_manifest' | 'decision_request';
+    payload: Json;
+    evidenceRefs: EvidenceRef[];
+}
+export interface Probe {
+    probeId: Id;
+    revision: number;
+    target: RunTarget;
+    kind: 'read-status' | 'read-log-delta' | 'read-artifact-manifest' | 'read-validation-result';
+    scopeId: Id;
+    expiresAt: string;
+    timeoutMs: number;
+    maxBytes: number;
+}
+export interface SourceCapabilities {
+    stableAttempt: boolean;
+    terminalEvents: boolean;
+    incrementalCursor: boolean;
+    exclusiveNotificationOwner: boolean;
+}
+export interface SourceAdapter {
+    readonly adapterId: string;
+    readonly capabilities: SourceCapabilities;
+    read(target: RunTarget, cursor: Json | undefined, signal: AbortSignal): Promise<{
+        observations: Observation[];
+        nextCursor: Json;
+        gap: boolean;
+    }>;
+    probes(target: RunTarget, basis: Basis): Promise<readonly Probe[]>;
+    execute(probe: Probe, signal: AbortSignal): Promise<Observation[]>;
+    close(): Promise<void>;
+}
+export type QuestionKey = 'meaningful_progress' | 'unresolved_blocker' | 'needs_host_decision' | 'repeating_without_new_information' | 'claim_conflicts_with_evidence' | 'context_sufficient';
+export interface Judgment {
+    basis: Basis;
+    model: string;
+    questionSet: 'watcher-q1';
+    probabilities: Record<QuestionKey, number>;
+    receivedAt: string;
+    inputTokens: number;
+    discarded: boolean;
+}
+export interface JudgePort {
+    evaluate(basis: Basis, state: Json, signal: AbortSignal): Promise<Judgment>;
+    chooseProbe(basis: Basis, state: Json, candidates: readonly Probe[], signal: AbortSignal): Promise<Id | 'none'>;
+    /** Optional availability check (e.g. credentials resolved lazily from the host); absent means always ready. */
+    ready?(): Promise<{
+        ready: boolean;
+        reason?: string;
+        model?: string;
+    }>;
+}
+export type AttentionReason = 'task.failed' | 'task.terminal' | 'deadline.exceeded' | 'decision.required' | 'blocker.unresolved' | 'progress.repeating' | 'claim.conflict' | 'evidence.insufficient' | 'dependency.ready' | 'monitor.degraded' | 'target.changed';
+export interface AttentionEnvelope {
+    schemaVersion: 1;
+    envelopeId: Id;
+    episodeId: Id;
+    episodeRevision: number;
+    watchId: Id;
+    generation: number;
+    missionRevision: number;
+    controlRevision: number;
+    ownerBindingEpoch: number;
+    target: Target;
+    reasonCode: AttentionReason;
+    summary: string;
+    evidenceRefs: EvidenceRef[];
+    requiredNextStep: 'inspect-current-watch-before-acting';
+    occurredAt: string;
+    validUntil: string;
+}
+export interface HostAck {
+    schemaVersion: 1;
+    requestId: Id;
+    watchId: Id;
+    generation: number;
+    episodeId: Id;
+    expectedEpisodeRevision: number;
+    action: 'received' | 'investigating' | 'defer' | 'resolved' | 'dismiss';
+    reason: string;
+    until?: string;
+    evidenceIds: Id[];
+}
+export interface VerifiedConsumerResponse {
+    responseId: Id;
+    deliveryRef: Id;
+    ownerBindingEpoch: number;
+    digest: string;
+    body: HostAck;
+}
+export interface ManagedDeliveryPort {
+    /** New managed relay adapter. Never fallback to direct Pi injection. */
+    /**
+     * decision-delta 2026-10-07 (per-watch scope, design 9.6): optional scope the event is
+     * captured under. Omitted -> the adapter's source-wide default scope (legacy behaviour).
+     */
+    publish(frozenRequestBytes: Uint8Array, scope?: {
+        scopeId: Id;
+        revision: number;
+    }): Promise<import('./relay-next.interfaces').ManagedReceipt>;
+    reconcile(eventId: Id): Promise<import('./relay-next.interfaces').ManagedReceipt>;
+    advanceScope(operationId: Id, scopeId: Id, expectedRevision: number, nextRevision: number, state: 'active' | 'paused' | 'closed'): Promise<Json>;
+    withdraw(operationId: Id, eventId: Id, reason: string): Promise<import('./relay-next.interfaces').WithdrawResult>;
+    readResponses(after: number): Promise<{
+        cursor: number;
+        responses: VerifiedConsumerResponse[];
+        resyncRequired: boolean;
+    }>;
+    confirmApplied(operationId: Id, responseId: Id, result: import('./relay-next.interfaces').ApplicationResult): Promise<void>;
+    close(): Promise<void>;
+}
+export interface Clock {
+    wallNow(): number;
+    monotonicNow(): number;
+}
+export interface Transaction {
+    getWatch(watchId: Id): WatchSpec | undefined;
+    compareRevision(basis: Basis): boolean;
+    persistCommandResult(requestId: Id, digest: string, result: Json): void;
+}
+export interface Store {
+    /** Synchronous, bounded transaction body: external I/O is forbidden. */
+    transaction<T>(runtimeEpoch: number, body: (tx: Transaction) => T): T;
+    close(): void;
+}
+export interface WatchService {
+    register(requestId: Id, candidate: RegisterCandidate, actor: ActorContext): Promise<WatchSpec>;
+    list(cursor: string | undefined, limit: number, actor: ActorContext): Promise<Json>;
+    inspect(watchId: Id, actor: ActorContext): Promise<Json>;
+    check(requestId: Id, watchId: Id, expectedControlRevision: number, actor: ActorContext): Promise<{
+        inspectionId: Id;
+    }>;
+    /** Internal response pump only. No independent network ACK endpoint. */
+    applyResponse(response: VerifiedConsumerResponse): Promise<import('./relay-next.interfaces').ApplicationResult>;
+    control(requestId: Id, watchId: Id, expectedControlRevision: number, action: 'pause' | 'close' | 'resume', reason: string, actor: ActorContext): Promise<Json>;
+}

package/dist/contracts/interfaces.js

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

package/dist/contracts/policy-defaults.json

@@ -0,0 +1,61 @@
+{
+  "schemaVersion": 1,
+  "status": "design-initial-values-not-performance-results",
+  "semanticMode": "shadow",
+  "jevConsentDefault": false,
+  "model": "jev-1.13.0",
+  "questionSet": "watcher-q1",
+  "thresholds": {
+    "contextSufficient": 0.75,
+    "needsHostDecision": 0.85,
+    "unresolvedBlocker": 0.85,
+    "repeating": 0.9,
+    "claimConflict": 0.85
+  },
+  "scheduler": {
+    "pollMinMs": 30000,
+    "pollMaxMs": 300000,
+    "maxSilenceMs": 900000,
+    "maxJevInFlight": 2,
+    "maxProbeInFlight": 4,
+    "maxJudgeRequestsPerWatchDay": 200,
+    "maxJudgeRequestsPerRootDay": 2000,
+    "judgeTimeoutMs": 10000,
+    "maxJudgeAttempts": 3
+  },
+  "capacity": {
+    "maxActiveWatches": 32,
+    "maxGroupChildren": 16,
+    "maxEvidenceEvents": 16,
+    "stateMaxBytes": 24576,
+    "evidenceMaxBytes": 12288,
+    "maxProbesPerInspection": 1,
+    "maxProbesPerEpisode": 2,
+    "rootSoftBytes": 1073741824,
+    "rootHardBytes": 2147483648
+  },
+  "attention": {
+    "transport": "relay",
+    "defaultModelMode": "display",
+    "episodeCooldownMs": 60000,
+    "ttlMs": 120000,
+    "resultTtlMs": 86400000,
+    "maxRequestsPerEpisode": 1,
+    "batchSize": 1
+  },
+  "retention": {
+    "closedEvidenceDays": 7,
+    "closedStructuredDays": 30,
+    "retainOpenAndUnknown": true
+  },
+  "relayManaged": {
+    "requiredWireMinor": 2,
+    "dispatchCooldownMs": 60000,
+    "batchSize": 1,
+    "sourceScopeProofMaxMs": 1000,
+    "consumerGuardTimeoutMs": 1000,
+    "maximumEventAgeMs": 86400000,
+    "maximumEventTtlMs": 86400000,
+    "dedupRetentionDays": 30
+  }
+}

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