instar 1.3.4 → 1.3.6

package/dist/monitoring/FrameworkIssueLedger.d.ts

@@ -0,0 +1,185 @@
+export declare const ISSUE_BUCKETS: readonly ["framework-limitation", "instar-integration-gap", "generic-agent-mistake"];
+export type IssueBucket = (typeof ISSUE_BUCKETS)[number];
+export declare const ISSUE_SEVERITIES: readonly ["low", "medium", "high"];
+export type IssueSeverity = (typeof ISSUE_SEVERITIES)[number];
+export declare const ISSUE_STATUSES: readonly ["open", "spec'd", "fixed", "wont-fix"];
+export type IssueStatus = (typeof ISSUE_STATUSES)[number];
+export declare const PLAYBOOK_STATUSES: readonly ["none", "candidate", "extracted", "superseded"];
+export type PlaybookStatus = (typeof PLAYBOOK_STATUSES)[number];
+export interface FrameworkIssueLedgerOptions {
+    dbPath: string;
+    /** Override clock for deterministic tests. */
+    now?: () => number;
+}
+/** What Stage B emits per observation (spec §5). */
+export interface RecordObservationInput {
+    framework: string;
+    bucket: IssueBucket;
+    title: string;
+    severity?: IssueSeverity;
+    /** Conservative auto-merge key (spec §13.3). Required — identifies the canonical issue. */
+    dedupKey: string;
+    /** Richer fingerprint for probable-dup review (spec §13.3). */
+    signature?: string;
+    /** OPAQUE reference only — path+line, log ref, PR#, sentinel-event id (spec §13.2/§17). */
+    evidence?: string;
+    observedVersion?: string;
+    tickId?: string;
+    /**
+     * Collapses repeated observations of the same open issue within a fix-window
+     * to one episode (spec §13.4). Defaults to the observed version so an unfixed
+     * issue accrues at most one episode per version span.
+     */
+    episodeKey?: string;
+    /** Forced primary when dual-tagged (spec §6). */
+    bucketPrimary?: IssueBucket;
+    relatedSpec?: string;
+}
+export interface RecordObservationResult {
+    issueId: string;
+    created: boolean;
+    episodeRecorded: boolean;
+    recurrenceCount: number;
+    probableLoop: boolean;
+}
+export interface IssueRow {
+    id: string;
+    framework: string;
+    bucket: IssueBucket;
+    bucketPrimary: IssueBucket | null;
+    title: string;
+    severity: IssueSeverity;
+    status: IssueStatus;
+    dedupKey: string;
+    signature: string | null;
+    recurrenceCount: number;
+    firstSeenVersion: string | null;
+    lastSeenVersion: string | null;
+    fixedInVersion: string | null;
+    regressedFromIssueId: string | null;
+    playbookStatus: PlaybookStatus;
+    wontFixReason: string | null;
+    relatedSpec: string | null;
+    probableLoop: boolean;
+    createdAt: number;
+    updatedAt: number;
+    /** Derived at read (spec §13.4) — never stored, so a re-classification can't stale it. */
+    generalizable: boolean;
+    /** Derived at read: severityWeight × recurrenceCount × recency decay (spec §13.4). */
+    impactScore: number;
+}
+export interface ListIssuesQuery {
+    framework?: string;
+    bucket?: IssueBucket;
+    status?: IssueStatus;
+    limit?: number;
+}
+export interface PlaybookQuery {
+    targetFramework: string;
+    limit?: number;
+}
+/** A single issue Stage-B forensics produced for a run (everything but the
+ *  per-run framework/tickId, which `captureRun` supplies). */
+export type ForensicFinding = Omit<RecordObservationInput, 'framework' | 'tickId'>;
+export interface CaptureRunInput {
+    framework: string;
+    tickId?: string;
+    findings: ForensicFinding[];
+}
+export interface CaptureRunResult {
+    runId: string;
+    framework: string;
+    findingsCount: number;
+    observationsWritten: number;
+    newIssues: number;
+    /** Previously-fixed issues whose signature/dedupKey matches a new finding —
+     *  surfaced for human regression review, NOT auto-linked (spec §13.5). */
+    regressionCandidates: Array<{
+        findingDedupKey: string;
+        candidateIssueId: string;
+    }>;
+}
+export interface CaptureStats {
+    totalRuns: number;
+    totalObservationsWritten: number;
+    lastRanAt: number | null;
+    byFramework: Array<{
+        framework: string;
+        runs: number;
+        observations: number;
+        lastRanAt: number;
+    }>;
+}
+export declare function scanForSecret(s: string): boolean;
+export declare class FrameworkIssueLedger {
+    private db;
+    private now;
+    constructor(opts: FrameworkIssueLedgerOptions);
+    /** Stable list of frameworks the ledger has seen — for the route allowlist (spec §5/§17). */
+    knownFrameworks(): string[];
+    /**
+     * Record one Stage-B observation. Finds-or-creates the canonical issue via
+     * (framework, dedupKey); collapses the observation into a distinct episode via
+     * episodeKey; increments the materialized recurrence_count only on a new
+     * episode (spec §13.4). All writes run in a single transaction (CAS-safe: the
+     * UNIQUE(issue_id, episode_key) index is the concurrency guard — a racing
+     * duplicate episode insert fails and is counted as already-recorded).
+     */
+    recordObservation(input: RecordObservationInput): RecordObservationResult;
+    /** Retention pruning — keep first N + last M observations per issue (spec §13.2). */
+    private pruneObservations;
+    /**
+     * Single-writer CAS mutate of an issue's mutable fields (status, bucket,
+     * playbookStatus, regression link, etc.). Follows CommitmentTracker's
+     * read-modify-write-with-version-check pattern; enum fields are validated.
+     * `wont-fix` requires a reason (spec §13.7).
+     */
+    updateIssue(issueId: string, patch: Partial<{
+        status: IssueStatus;
+        bucket: IssueBucket;
+        bucketPrimary: IssueBucket | null;
+        playbookStatus: PlaybookStatus;
+        fixedInVersion: string | null;
+        regressedFromIssueId: string | null;
+        wontFixReason: string | null;
+        relatedSpec: string | null;
+    }>): IssueRow | null;
+    /**
+     * Suggest a regression link: a new issue whose signature/dedupKey matches a
+     * previously-`fixed` issue is a candidate regression (spec §13.5). Returns the
+     * matching fixed issues (does NOT auto-link — review decides).
+     */
+    suggestRegressions(input: {
+        framework: string;
+        dedupKey: string;
+        signature?: string | null;
+    }): IssueRow[];
+    getIssue(id: string): IssueRow | null;
+    listIssues(q?: ListIssuesQuery): IssueRow[];
+    /**
+     * The onboarding playbook for `targetFramework`: generalizable lessons from
+     * PRIOR (other) frameworks, ranked by impactScore (spec §13.6). The playbook
+     * for X is sourced from frameworks != X — never X's own issues.
+     */
+    playbook(q: PlaybookQuery): IssueRow[];
+    observationCount(issueId: string): number;
+    /**
+     * Stage-B auto-capture (spec §5, §19.2). The single atomic entry point the
+     * mentor tick calls after forensics: it writes every finding to the ledger
+     * (no "remember to log" — zero-manual-capture) and ALWAYS logs the run to the
+     * capture-funnel, even when `findings` is empty. That funnel row is what makes
+     * an inert/broken writer visible: a run that produced zero observations is
+     * recorded as a run, so "ran, found nothing" is distinguishable from "never
+     * ran." Regression candidates are surfaced for review, never auto-linked
+     * (spec §13.5 — promotion is not the writer's call).
+     */
+    captureRun(input: CaptureRunInput): CaptureRunResult;
+    /** Capture-funnel observability (spec §5/§18). Surfaces ticks→observations so
+     *  a writer that runs but never writes is visible. */
+    captureStats(): CaptureStats;
+    private rowToIssue;
+    close(): void;
+}
+/** Clamp a list limit to 1..500 (spec §5/§17). */
+export declare function clampLimit(raw: unknown): number;
+//# sourceMappingURL=FrameworkIssueLedger.d.ts.map

package/dist/monitoring/FrameworkIssueLedger.d.ts.map

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