instar 0.28.92 → 0.28.94

package/dist/core/ProjectDriftChecker.d.ts

@@ -0,0 +1,215 @@
+/**
+ * ProjectDriftChecker — signal-only drift detection for project-scope rounds.
+ *
+ * Spec: docs/specs/PROJECT-SCOPE-SPEC.md Phase 1.4.
+ *
+ * What this does:
+ *   Given a spec + the files it references, ask the LLM whether the spec's
+ *   stated premises still match what's on disk today. Returns one of four
+ *   verdicts: no-drift, minor-drift, premise-violated, manual-review-required.
+ *
+ * Authority model (P1, signal-vs-authority):
+ *   This is a *signal* producer only. The verdict is recorded on the round
+ *   as `lastDriftVerdict` and surfaced in the digest. The decision to start
+ *   or block a round is made by ProjectRoundRunner using verifiable
+ *   artifacts (frontmatter tags, `gh pr view`, CI status). The drift verdict
+ *   alone never authorizes or blocks a transition.
+ *
+ * Hardening:
+ *   - All file paths are jailed under `targetRepoPath` (jailPath utility
+ *     from StageTransitionValidator). `../`, absolute paths, and symlinks
+ *     that escape are rejected.
+ *   - Spec body is wrapped in `<UNTRUSTED_SPEC_BODY>...</UNTRUSTED_SPEC_BODY>`;
+ *     each referenced file in `<UNTRUSTED_FILE_CONTENT path="..." hash="...">`.
+ *     The system prompt explicitly distrusts content inside these blocks.
+ *   - LLM output is JSON.parse'd and structurally validated against the
+ *     DriftVerdict shape. Anything malformed → `manual-review-required`
+ *     (reason `schema-fail`).
+ *   - Each evidenceCitation is re-verified by the checker: open the file,
+ *     check byteRange in bounds, render slice as `excerpt`. Citations that
+ *     don't resolve are dropped. If ALL citations drop (and at least one
+ *     was claimed), verdict is downgraded to `manual-review-required`
+ *     with reason `failed-citation-verification`. The verified excerpt
+ *     is what gets shown — never the LLM-claimed text.
+ *
+ * Input bounds (normative; spec § Phase 1.4):
+ *   - Max 5 files referenced per spec
+ *   - Per-file cap: 2,000 lines OR 80 KB (whichever is smaller)
+ *   - Total prompt budget: 50,000 tokens, estimated as chars / 4
+ *   - Over-budget → `manual-review-required` with reason `over-budget`.
+ *     Never silently summarize.
+ *
+ * Failure modes:
+ *   - LLM timeout (30s, configurable): one retry; if both fail, return
+ *     `manual-review-required` with reason `timeout`.
+ *   - Empty/missing spec body → `manual-review-required` (`empty-spec`).
+ *   - All referenced files missing → `manual-review-required`
+ *     (`deleted-files`).
+ *   - No IntelligenceProvider configured → `manual-review-required`
+ *     (`no-provider`). The round-runner halts the round; user attention.
+ *
+ * NOT in this PR (lands in Phase 1b PR 2):
+ *   - Cost ledger with file lock (advisory flock on .instar/local/drift-spend.lock)
+ *   - Cache (sha256 key from promptTemplateVersion+modelId+specBodySha+filehashes)
+ *   - Mtime fast-path
+ *   These are additive; the checker as written returns a correct verdict
+ *   on every call, just without rate-limit or memoization protection. The
+ *   round-runner (Phase 1.5) is the consumer; until it ships, no caller
+ *   wires this up.
+ */
+import type { DriftVerdict, IntelligenceProvider, VerifiedCitation } from './types.js';
+import type { ProjectDriftCheckerCache } from './ProjectDriftCheckerCache.js';
+import { DriftSpendLedger } from './DriftSpendLedger.js';
+/** Bumped whenever the system prompt changes; part of the future cache key. */
+export declare const DRIFT_PROMPT_TEMPLATE_VERSION = 1;
+/** Hard limits per spec § Phase 1.4. Exported so tests can dial them down. */
+export declare const DRIFT_LIMITS: {
+    readonly maxReferencedFiles: 5;
+    readonly perFileBytes: number;
+    readonly perFileLines: 2000;
+    readonly totalTokenBudget: 50000;
+    /** Rough char→token estimate; 4 chars per token is a conservative upper bound. */
+    readonly charsPerToken: 4;
+    readonly defaultTimeoutMs: 30000;
+    readonly excerptDisplayCap: 240;
+};
+export interface DriftCheckInput {
+    /** Project id — used for telemetry/audit only; the checker does no project lookup. */
+    projectId: string;
+    /** Round index within the project — telemetry only. */
+    roundIndex: number;
+    /**
+     * Absolute target repo root. Every file path in this call must resolve
+     * inside this directory after realpath.
+     */
+    targetRepoPath: string;
+    /** Spec markdown path; absolute or relative to targetRepoPath. Jailed. */
+    specPath: string;
+    /**
+     * Files the spec claims to depend on — typically extracted from spec
+     * frontmatter `referencedFiles` or `sourceDocs`. Caller is responsible
+     * for the list; the checker is responsible for enforcing the limits.
+     */
+    referencedFiles: string[];
+    /** Optional override for the 30s timeout (tests dial this down). */
+    timeoutMs?: number;
+    /**
+     * Resolved model id, surfaced into the prompt so a future cache key can
+     * key on it. Not used at the call site today (the provider chooses the
+     * model based on `options.model`), but the spec requires it be part of
+     * the cache key — passing it through here keeps the contract aligned.
+     */
+    modelId?: string;
+}
+interface PreparedFile {
+    /** Path the LLM sees, relative to targetRepoPath. */
+    relPath: string;
+    /** Absolute, jailed path. */
+    absPath: string;
+    /** Raw bytes read. */
+    bytes: Buffer;
+    /** sha256 of the bytes, displayed in the untrusted block header. */
+    hash: string;
+}
+/**
+ * Lightweight container for LLM-returned citations BEFORE verification.
+ * After verification the shape is `VerifiedCitation` (exported from types).
+ */
+interface UnverifiedCitation {
+    file?: unknown;
+    byteRange?: unknown;
+    excerpt?: unknown;
+}
+interface ParsedLlmResponse {
+    verdict?: unknown;
+    rationale?: unknown;
+    evidenceCitations?: unknown;
+}
+export interface ProjectDriftCheckerConfig {
+    intelligence?: IntelligenceProvider;
+    /** Defaults to spec § Phase 1.4 hard limits; tests can override. */
+    limits?: Partial<typeof DRIFT_LIMITS>;
+    /** Optional verdict cache. When absent, every call recomputes from scratch. */
+    cache?: ProjectDriftCheckerCache;
+    /** Optional spend ledger. When absent, no cap enforcement. */
+    ledger?: DriftSpendLedger;
+    /**
+     * Best-effort cost estimate per call in USD; ledger pre-reserves this
+     * amount before the LLM call. Default $0.01 — conservative for the
+     * 'balanced' tier on the 50k-token-budget cap.
+     */
+    estimatedCostPerCallUsd?: number;
+}
+export declare class ProjectDriftChecker {
+    private intelligence?;
+    private limits;
+    private cache?;
+    private ledger?;
+    private estimatedCostPerCallUsd;
+    constructor(config?: ProjectDriftCheckerConfig);
+    run(input: DriftCheckInput): Promise<DriftVerdict>;
+}
+declare class TimeoutError extends Error {
+    constructor(ms: number);
+}
+interface PromptInput {
+    specBody: string;
+    files: PreparedFile[];
+    modelId?: string;
+    templateVersion: number;
+    deletedFiles: string[];
+}
+/**
+ * Build the LLM prompt. The system block tells the model to distrust
+ * everything inside the UNTRUSTED_* blocks and to respond ONLY with a JSON
+ * object of the documented shape.
+ */
+export declare function buildPrompt(input: PromptInput): string;
+/**
+ * Extract the first JSON object from a raw LLM response. Tolerates leading
+ * prose, code fences, etc. Returns null on no match or parse failure.
+ */
+export declare function extractJson(raw: string): ParsedLlmResponse | null;
+type VerdictValidation = {
+    ok: true;
+    verdict: 'no-drift' | 'minor-drift' | 'premise-violated';
+    rationale: string;
+    citations: UnverifiedCitation[];
+} | {
+    ok: false;
+    reason: string;
+};
+/**
+ * Hand-rolled structural validator for the LLM's JSON output. Returns the
+ * normalized fields on success; a `reason` on failure. We avoid Ajv to keep
+ * the dep footprint flat.
+ */
+export declare function validateVerdict(parsed: ParsedLlmResponse): VerdictValidation;
+/**
+ * Re-verify each LLM-proposed citation against the prepared file bytes.
+ * Drops citations that don't resolve. Returns the verified slice itself —
+ * the LLM-claimed `excerpt` field is intentionally discarded.
+ */
+export declare function verifyCitations(claimed: UnverifiedCitation[], files: PreparedFile[], excerptCap: number): VerifiedCitation[];
+/**
+ * Stable cache key inputs for a drift check call. Exported so Phase 1b PR 2
+ * (cache + cost ledger) can wire this up without forking the implementation.
+ * Returns the inputs as an object — the consumer hashes them.
+ */
+export declare function cacheKeyInputs(promptTemplateVersion: number, modelId: string, specBytes: Buffer, referencedFileBytes: Array<{
+    relPath: string;
+    bytes: Buffer;
+}>): {
+    promptTemplateVersion: number;
+    modelId: string;
+    specBodySha: string;
+    sortedFileHashes: string[];
+};
+export { TimeoutError };
+/**
+ * Path used by the StageTransitionValidator's `jailPath` is the same one
+ * we use here; explicit re-export so other modules can import it from this
+ * file without depending on StageTransitionValidator directly.
+ */
+export { jailPath } from './StageTransitionValidator.js';
+//# sourceMappingURL=ProjectDriftChecker.d.ts.map

package/dist/core/ProjectDriftChecker.d.ts.map

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