crewly 1.20.193 → 1.20.195

package/dist/backend/backend/src/services/experiments/experiment.service.d.ts

@@ -0,0 +1,350 @@
+/**
+ * Experiment cards (issue #986, epic #982).
+ *
+ * An optimisation ticket carries an experiment: a hypothesis ("change X →
+ * metric Y from a to b"), a metric (Search Console / GA4 through the seo-ops
+ * skill), a baseline captured when the change ships and an observation
+ * window (default 14 days). When the window has settled the harness fetches
+ * the metric, labels the result worked / didn't / inconclusive (simple
+ * significance rules plus a minimum volume, see experiment-verdict.ts),
+ * resolves the agent's prediction, appends the result to the wiki
+ * experiment log and tells the owner.
+ *
+ * The experiment is a trace root: `traceId` (a run trace, `tr-…`; the ticket's
+ * trace when its ticket already has one) names the run, and
+ * the timeline records every step (created, shipped, baseline, each fetch
+ * failure, measured, logged, reported), so the whole run can be reviewed.
+ *
+ * State: `~/.crewly/experiments.json`. A tick (every 15 min) moves
+ * experiments forward, so restarts lose nothing.
+ *
+ * specs/experiment-cards.md
+ *
+ * @module services/experiments/experiment.service
+ */
+import { type ComponentLogger } from '../core/logger.service.js';
+import { type Experiment, type ExperimentMetric, type ExperimentStatus, type ExperimentTicketLink } from '../../types/experiment.types.js';
+import type { MetricFetcher } from './seo-ops-metric.fetcher.js';
+/** A notice for the owner (same shape as the ticket autopilot's). */
+export interface ExperimentOwnerNotice {
+    title: string;
+    message: string;
+    urgent: boolean;
+}
+/** The prediction calls the service makes (record-prediction / resolve-prediction). */
+export interface ExperimentPredictions {
+    make(session: string, statement: string, confidence: number, resolveBy: string): Promise<{
+        id: string;
+    }>;
+    resolve(session: string, id: string, outcome: string, accurate: boolean): Promise<unknown>;
+}
+/**
+ * Whether the linked ticket is done and when. `at` is null when the ticket is
+ * done but the time of its done transition is not recorded.
+ */
+export type TicketShipState = {
+    done: false;
+} | {
+    done: true;
+    at: string | null;
+};
+/** Dependencies. */
+export interface ExperimentServiceDeps {
+    /** JSON store */
+    storeFile: string;
+    /** Fetch a metric over a window (seo-ops) */
+    fetchMetric: MetricFetcher;
+    /** Whether the linked ticket shipped, dated by its done transition (never its updatedAt) */
+    ticketShipState?: (link: ExperimentTicketLink) => Promise<TicketShipState>;
+    /** Note the experiment on its ticket (best effort) */
+    noteOnTicket?: (link: ExperimentTicketLink, note: string) => Promise<void>;
+    predictions?: ExperimentPredictions;
+    /** Append a result to the wiki experiment log; false = not written (no vault) */
+    writeLog?: (experiment: Experiment, entry: string) => Promise<boolean>;
+    /** Tell the owner; false = not sent (Slack not connected) */
+    notifyOwner?: (notice: ExperimentOwnerNotice) => Promise<boolean>;
+    /** Does a file exist (the seo-ops config) */
+    fileExists?: (file: string) => Promise<boolean>;
+    now?: () => Date;
+    logger?: ComponentLogger;
+}
+/** Input of {@link ExperimentService.create}. */
+export interface CreateExperimentInput {
+    title?: unknown;
+    hypothesis?: unknown;
+    direction?: unknown;
+    expected?: unknown;
+    metric?: unknown;
+    windowDays?: unknown;
+    ticket?: unknown;
+    confidence?: unknown;
+    /** When the change went live (ISO). Required when the linked ticket is already done with no recorded done time. */
+    shippedAt?: unknown;
+}
+/** An error with an HTTP status. */
+export declare class ExperimentError extends Error {
+    readonly status: number;
+    /**
+     * @param status - HTTP status
+     * @param message - What went wrong
+     */
+    constructor(status: number, message: string);
+}
+/**
+ * A GA4 landing-page filter as a path: GA4 reports landing pages as paths, so
+ * a full URL is reduced to its path and any query string / fragment dropped
+ * (`https://site/x/?utm=1` → `/x/`).
+ *
+ * @param page - Page as given
+ * @returns The path
+ * @throws ExperimentError(400) when it is a URL that cannot be read
+ */
+export declare function ga4PagePath(page: string): string;
+/**
+ * Validate a metric definition.
+ *
+ * @param raw - Body
+ * @returns Metric
+ * @throws ExperimentError(400) with what is wrong
+ */
+export declare function validateMetric(raw: unknown): ExperimentMetric;
+/**
+ * Validate a ticket link.
+ *
+ * @param raw - Body
+ * @returns Link or undefined
+ * @throws ExperimentError(400)
+ */
+export declare function validateTicketLink(raw: unknown): ExperimentTicketLink | undefined;
+/**
+ * How a ticket link reads.
+ *
+ * @param link - Link
+ * @returns e.g. "ce-site/T-12" or "TKT-40"
+ */
+export declare function ticketLabel(link: ExperimentTicketLink): string;
+/**
+ * The metric as one line.
+ *
+ * @param m - Metric
+ * @returns e.g. "gsc clicks · page https://… · query visa"
+ */
+export declare function metricLabel(m: ExperimentMetric): string;
+/**
+ * The result as markdown (wiki log entry and owner message share it).
+ *
+ * @param e - A measured experiment
+ * @returns Markdown
+ */
+export declare function resultSummary(e: Experiment): string;
+/**
+ * Experiment cards: store, lifecycle and the measuring tick.
+ */
+export declare class ExperimentService {
+    private readonly deps;
+    private static instance;
+    private readonly logger;
+    private readonly now;
+    private chain;
+    private timer;
+    /** A tick is running (fetches can be slow; ticks never overlap) */
+    private ticking;
+    /** Experiments being measured right now (a measureNow racing a tick fetches once) */
+    private readonly measuring;
+    /**
+     * @param deps - Dependencies
+     */
+    constructor(deps: ExperimentServiceDeps);
+    /**
+     * The installed service (null before boot).
+     *
+     * @returns Service or null
+     */
+    static getInstance(): ExperimentService | null;
+    /**
+     * Install the process service.
+     *
+     * @param service - Service, or null to clear
+     */
+    static setInstance(service: ExperimentService | null): void;
+    /**
+     * Start the periodic tick (runs once right away).
+     *
+     * @param intervalMs - Interval (0 = no timer; tests call {@link tick})
+     */
+    start(intervalMs?: number): void;
+    /** Stop the tick. */
+    stop(): void;
+    /**
+     * Run one store operation at a time.
+     *
+     * @param fn - Operation
+     * @returns Its result
+     */
+    private serial;
+    /**
+     * Read the store.
+     *
+     * @returns Store data (empty when missing)
+     */
+    private load;
+    /**
+     * Write the store atomically.
+     *
+     * @param data - Store data
+     */
+    private save;
+    /**
+     * Load, change one experiment, save.
+     *
+     * @param id - Experiment id
+     * @param fn - Change (mutates the experiment)
+     * @returns The experiment after the change
+     * @throws ExperimentError(404) when not found
+     */
+    private mutate;
+    /**
+     * Add a timeline entry.
+     *
+     * @param e - Experiment
+     * @param event - Event name
+     * @param detail - Optional detail
+     */
+    private record;
+    /**
+     * All experiments, newest first.
+     *
+     * @param filter - Optional status / ticket filter
+     * @returns Experiments
+     */
+    list(filter?: {
+        status?: string;
+        ticket?: string;
+    }): Promise<Experiment[]>;
+    /**
+     * One experiment.
+     *
+     * @param id - EXP-n
+     * @returns Experiment or null
+     */
+    get(id: string): Promise<Experiment | null>;
+    /**
+     * Create an experiment card.
+     *
+     * @param input - Hypothesis, metric, window, ticket, confidence
+     * @param caller - Agent session, or `owner`
+     * @returns The new experiment (status planned)
+     * @throws ExperimentError(400) on invalid input
+     */
+    create(input: CreateExperimentInput, caller: string): Promise<Experiment>;
+    /**
+     * Mark an experiment shipped: fix its windows, record the prediction and
+     * capture the baseline.
+     *
+     * @param id - EXP-n
+     * @param caller - Who shipped it
+     * @param shippedAt - When it went live (default now; not in the future)
+     * @returns The experiment
+     * @throws ExperimentError(404 / 409 / 400)
+     */
+    ship(id: string, caller: string, shippedAt?: string): Promise<Experiment>;
+    /**
+     * Cancel an experiment that has not been measured.
+     *
+     * @param id - EXP-n
+     * @param caller - Who
+     * @param reason - Why
+     * @returns The experiment
+     * @throws ExperimentError(404 / 409)
+     */
+    cancel(id: string, caller: string, reason?: string): Promise<Experiment>;
+    /**
+     * Measure a due experiment now (instead of waiting for the tick).
+     *
+     * @param id - EXP-n
+     * @returns The experiment
+     * @throws ExperimentError(404 / 409) when it is not running or not yet due
+     */
+    measureNow(id: string): Promise<Experiment>;
+    /**
+     * Move every experiment forward: ship planned ones whose ticket shipped,
+     * retry missing baselines, measure due ones, finish follow-ups.
+     *
+     * @returns Counts of what happened (zeros when a tick is already running)
+     */
+    tick(): Promise<{
+        shipped: number;
+        measured: number;
+    }>;
+    /**
+     * One pass over all experiments (see {@link tick}).
+     *
+     * @returns Counts of what happened
+     */
+    private runTick;
+    /**
+     * Whether a running experiment's fetches are backing off: after
+     * MAX_FETCH_ATTEMPTS failures in a row the tick retries once every
+     * FETCH_BACKOFF_MS instead of every tick.
+     *
+     * @param e - Experiment
+     * @param nowMs - Now
+     * @returns True to skip this tick
+     */
+    private backingOff;
+    /**
+     * The linked ticket is done but its done time is not recorded: the card
+     * cannot be dated, so it waits for an explicit ship. Recorded (and the
+     * owner told) once.
+     *
+     * @param id - EXP-n
+     */
+    private shipTimeUnknown;
+    /**
+     * Record the creating agent's prediction that the hypothesis holds.
+     *
+     * @param id - EXP-n
+     */
+    private recordPrediction;
+    /**
+     * A fetch failed: count it, and tell the owner once when it keeps failing.
+     *
+     * @param id - EXP-n
+     * @param step - baseline / result
+     * @param err - The error
+     */
+    private fetchFailed;
+    /**
+     * Fetch the baseline window.
+     *
+     * @param id - EXP-n
+     */
+    private captureBaseline;
+    /**
+     * Fetch the observation window and label the result.
+     *
+     * @param id - EXP-n
+     */
+    private measure;
+    /**
+     * One measurement (see {@link measure}).
+     *
+     * @param id - EXP-n
+     */
+    private measureOnce;
+    /**
+     * After a result: resolve the prediction, write the wiki log, tell the
+     * owner. Each step is retried by later ticks until it lands.
+     *
+     * @param id - EXP-n
+     */
+    private followUp;
+}
+/**
+ * Is this a status filter value?
+ *
+ * @param v - Query value
+ * @returns The status or undefined
+ */
+export declare function statusFilter(v: unknown): ExperimentStatus | undefined;
+//# sourceMappingURL=experiment.service.d.ts.map

package/dist/backend/backend/src/services/experiments/experiment.service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"experiment.service.d.ts","sourceRoot":"","sources":["../../../../../../backend/src/services/experiments/experiment.service.ts"],"names":[],"mappings":"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"}