scip-query 0.20.0 → 0.21.1

package/dist/repository-text-C0Q8VYdN.d.ts

@@ -0,0 +1,19 @@
+type SourceSemanticFreshnessState = 'aligned' | 'stale' | 'unavailable';
+/**
+ * Freshness of one source observation. Exact text is read from the current
+ * worktree; semantic alignment compares those bytes with the indexed input
+ * fingerprint when the file has compiler facts.
+ */
+interface SourceObservationFreshness {
+    exactText: {
+        state: 'current';
+        basis: 'working-tree-read';
+        sha256: string;
+    };
+    semantic: {
+        state: SourceSemanticFreshnessState;
+        basis: 'indexed-input-fingerprint' | 'no-compiler-document' | 'fingerprint-unavailable';
+    };
+}
+
+export type { SourceObservationFreshness as S, SourceSemanticFreshnessState as a };

package/dist/runtime.d.ts

@@ -1,8 +1,19 @@
-import { P as ProjectConfig, a as SupportedLanguage, T as TypeScriptProjectMode } from './config-types-jVM3D7MA.js';
-export { O as OBSERVATION_RECEIPT_SCHEMA_VERSION, b as ObservationAuthorityKind, c as ObservationReceipt, d as ObservationReceiptComparison, e as compareObservationReceipts, i as isObservationReceipt } from './config-types-jVM3D7MA.js';
+import { P as ProjectConfig, W as WatchConfig, b as WatchResourceBudgetConfig, a as SupportedLanguage, T as TypeScriptProjectMode, D as DerivedObservationStateAuthority, O as ObservationSourceKind, c as ObservationReceipt } from './config-types-B9B60MiR.js';
+export { d as DecodedObservationReceipt, L as LEGACY_OBSERVATION_RECEIPT_SCHEMA_VERSION, e as OBSERVATION_IDENTITY_CANONICALIZATION_VERSION, f as OBSERVATION_IDENTITY_HASH_ALGORITHM, g as OBSERVATION_IDENTITY_SCHEMA_VERSION, h as OBSERVATION_RECEIPT_SCHEMA_VERSION, i as OBSERVATION_STATE_AUTHORITY_POLICY_VERSION, j as ObservationAuthorityKind, k as ObservationComparedFact, l as ObservationComparisonReason, m as ObservationIdentity, n as ObservationReceiptComparison, o as ObservationReceiptV1, p as ObservationReceiptV2, q as ObservationRelationshipJudgment, r as ObservationRelationshipState, s as ObservationSourceFact, t as ObservationStabilityProof, u as ObservationStabilityProofKind, v as ObservationStateAuthority, R as RelevantInputIdentity, w as RelevantInputRelationshipJudgment, x as compareObservationReceipts, y as createObservationIdentity, z as decodeObservationReceipt, A as deriveObservationStateAuthority, B as isObservationReceipt, C as observationReceiptGenerationIdentity, E as observationReceiptStabilityLabel, F as observationReceiptWorkspaceIdentity } from './config-types-B9B60MiR.js';
 import { watch } from 'chokidar';
-import { R as RefreshTrigger, W as WatcherStatus } from './scip-cli-BnEwZRLJ.js';
-export { g as getScipVersion, i as isScipInstalled, p as printScipInstallInstructions } from './scip-cli-BnEwZRLJ.js';
+import { R as RefreshTrigger, P as ProjectInputChangeJournal, W as WatcherStatus } from './scip-cli-H-n59izO.js';
+export { g as getScipVersion, i as isScipInstalled, p as printScipInstallInstructions } from './scip-cli-H-n59izO.js';
+
+/**
+ * One operating-system process instance. A PID alone names a reusable slot;
+ * the start token distinguishes successive processes that occupy that slot.
+ */
+interface ProcessIdentity {
+    version: 1;
+    pid: number;
+    platform: NodeJS.Platform;
+    startToken: string;
+}
 
 declare function resolveIndexStoragePaths(projectRoot: string, config?: ProjectConfig): {
     cacheDir: string;
@@ -11,6 +22,10 @@ declare function resolveIndexStoragePaths(projectRoot: string, config?: ProjectC
     metaPath: string;
 };
 
+type ResolvedWatchConfig = Omit<Required<WatchConfig>, 'resourceBudget'> & {
+    resourceBudget: Required<WatchResourceBudgetConfig>;
+};
+
 /**
  * Load project config from .scipquery.json in the project root.
  * Returns defaults for anything not specified.
@@ -22,20 +37,55 @@ declare function loadProjectConfig(projectRoot: string): ProjectConfig;
  */
 declare function initProjectConfig(projectRoot: string, languages: string[]): string;
 
+interface GitReader {
+    run(projectRoot: string, args: readonly string[]): string | undefined;
+    runResult(projectRoot: string, args: readonly string[]): GitCommandResult;
+}
+type GitCommandResult = {
+    kind: 'success';
+    output: string;
+} | {
+    kind: 'not-repository';
+} | {
+    kind: 'error';
+    message: string;
+};
+
+type ReindexActivityBudgetDecision = {
+    state: 'allowed';
+    rebuilt: number;
+    estimatedWriteBytes: number;
+} | {
+    state: 'paused';
+    reason: 'rebuild-count' | 'estimated-write-bytes' | 'activity-evidence';
+    until: number;
+    rebuilt: number;
+    estimatedWriteBytes: number;
+    detail: string;
+};
+
 interface WatcherOptions {
     projectRoot: string;
     config: ProjectConfig;
     languages?: SupportedLanguage[];
     reindexRunner?: ReindexRunner;
     subscriptionFactory?: WatchSubscriptionFactory;
+    budgetInspector?: WatchBudgetInspector;
+    gitReader?: GitReader;
+    outputDb?: string;
     clock?: WatchClock;
     stopTimeoutMs?: number;
     onStatus?: (status: WatcherStatus) => void;
-    onReindexComplete?: (durationMs: number, trigger: RefreshTrigger) => boolean | void;
+    onReindexComplete?: (durationMs: number, trigger: RefreshTrigger, context?: ReindexCompletionContext) => boolean | void;
     onReindexError?: (error: Error, trigger: RefreshTrigger) => void;
     onRefreshSuppressed?: (trigger: RefreshTrigger) => void;
     onError?: (error: Error) => void;
 }
+interface ReindexCompletionContext {
+    /** True when a filesystem or refresh event arrived after this run began. */
+    pendingChanges: boolean;
+}
+type WatchBudgetInspector = (outputDb: string, config: ResolvedWatchConfig['resourceBudget'], now: Date) => ReindexActivityBudgetDecision;
 interface ReindexRunRequest {
     projectRoot: string;
     config: ProjectConfig;
@@ -46,6 +96,10 @@ interface ReindexRunRequest {
     clojureConfigPath?: string;
     indexerConcurrency?: number;
     trigger: RefreshTrigger;
+    /** Exact watcher changes since the immutable generation named by the journal. */
+    changeJournal?: ProjectInputChangeJournal;
+    /** When false, skip full language indexers and keep the previous shard. Default true. */
+    allowExpensiveRebuild?: boolean;
 }
 interface ReindexWorkerLaunch {
     workerPath: string;
@@ -109,7 +163,7 @@ interface WatchClock {
  * Design:
  *  - Debounce: waits for a configurable quiet period after the last file change
  *  - Single-flight: only one reindex runs at a time, never queued
- *  - Dirty flag: changes during reindex schedule ONE follow-up
+ *  - Dirty flag: changes during reindex cancel stale work and schedule ONE follow-up
  *  - Cooldown: minimum interval between reindex completions
  *  - Atomic publish: the reindexer writes temp artifacts, then promotes them
  */
@@ -117,6 +171,7 @@ declare class Watcher {
     private projectRoot;
     private config;
     private watchConfig;
+    private outputDb;
     private languages?;
     private pnpmWorkspaces;
     private typescriptProjectMode?;
@@ -130,6 +185,7 @@ declare class Watcher {
     private onError;
     private reindexRunner;
     private subscriptionFactory;
+    private budgetInspector;
     private clock;
     private activeOperation;
     private stopPromise;
@@ -137,15 +193,24 @@ declare class Watcher {
     private status;
     private debounceTimer;
     private cooldownTimer;
+    private budgetTimer;
     private dirty;
     private changedFiles;
     private pendingTrigger;
+    private pendingChanges;
+    private pendingChangesComplete;
+    private pendingChangesIncompleteReason;
     private reindexInFlight;
     private lastReindexEnd;
     private fsWatchers;
     private sourcePollingFallbackStarted;
     private gitPollTimer;
     private lastGitState;
+    /** When unset, idle Git polls read HEAD/index from the filesystem instead of spawning git. */
+    private preferFilesystemGitState;
+    private watchGitLayout;
+    /** Project-relative cache directory; ignored so reindex artifacts do not wake the watcher. */
+    private localCacheWatchPath;
     private gitignoreFilter;
     private extraIgnore;
     private stopped;
@@ -167,16 +232,25 @@ declare class Watcher {
     private triggerReindex;
     private finishStop;
     private wallNow;
+    private inspectBudget;
     private reindexRequest;
     private setStatus;
+    private recordPendingChange;
+    private markPendingChangesIncomplete;
+    private consumePendingChangeJournal;
+    private restorePendingChangeJournal;
+    private resetPendingChanges;
     private clearDebounceTimer;
     private clearCooldownTimer;
+    private clearBudgetTimer;
     private startGitStatePolling;
     private pollGitState;
     private readGitState;
+    private readFilesystemGitState;
+    private readGitStateFromGit;
     private clearGitPollTimer;
 }
-declare function resolveReindexWorkerLaunch(request: ReindexRunRequest): ReindexWorkerLaunch;
+declare function resolveReindexWorkerLaunch(request: ReindexRunRequest, resolveParentIdentity?: (pid: number) => ProcessIdentity | null): ReindexWorkerLaunch;
 declare function createReindexRunner(options?: ReindexRunnerOptions): ReindexRunner;
 
 interface InstallSkillsResult {
@@ -193,15 +267,215 @@ interface InstallSkillsResult {
  */
 declare function installSkills(opts?: {
     quiet?: boolean;
+    homeDir?: string;
 }): InstallSkillsResult;
 
+/**
+ * What one parsed command invocation does to or learns about the world.
+ *
+ * A command name is not sufficient: one command can preview in one mode and
+ * mutate in another. The selected role follows the invocation's observable
+ * effect, not the subsystem that implements it.
+ */
+declare const COMMAND_OPERATION_ROLES: readonly ["repository-observation", "repository-preview", "mutation", "composite", "environment-observation", "tool-information"];
+type CommandOperationRole = (typeof COMMAND_OPERATION_ROLES)[number];
+type CommandOperationRuleCondition = {
+    kind: 'argument';
+    index: number;
+    equals: string | number | boolean;
+} | {
+    kind: 'option';
+    name: string;
+    equals: string | number | boolean;
+} | {
+    kind: 'option-present';
+    name: string;
+};
+interface CommandOperationRule {
+    when: CommandOperationRuleCondition;
+    role: CommandOperationRole;
+}
+/**
+ * Declarative rather than executable so descriptors, docs, validation, and
+ * runtime selection all inspect one finite contract.
+ */
+interface CommandOperationSelector {
+    defaultRole: CommandOperationRole;
+    rules?: readonly CommandOperationRule[];
+}
+interface CommandOperationInvocation {
+    args: readonly unknown[];
+    options: Readonly<Record<string, unknown>>;
+}
+declare function commandOperation(defaultRole: CommandOperationRole, rules?: readonly CommandOperationRule[]): CommandOperationSelector;
+declare function resolveCommandOperationRole(selector: CommandOperationSelector, invocation: CommandOperationInvocation): CommandOperationRole;
+declare function commandOperationRoles(selector: CommandOperationSelector): CommandOperationRole[];
+declare function isCommandOperationRole(value: unknown): value is CommandOperationRole;
+declare function operationObservesRepository(role: CommandOperationRole): boolean;
+
+declare const CLAIM_QUALIFICATION_SCHEMA_VERSION: 1;
+declare const CLAIM_ACTION_POLICY_VERSION: 1;
+declare const CLAIM_ORIGINS: readonly ["compiler-graph", "semantic-analysis", "repository-source", "change-history", "runtime-measurement", "heuristic", "mixed", "unknown"];
+type ClaimOrigin = (typeof CLAIM_ORIGINS)[number];
+declare const CLAIM_COVERAGE_STATES: readonly ["complete", "partial", "unknown"];
+type ClaimCoverageState = (typeof CLAIM_COVERAGE_STATES)[number];
+declare const PRODUCER_VALIDATION_STATUSES: readonly ["validated", "failed", "not-evaluated", "not-applicable"];
+type ProducerValidationStatus = (typeof PRODUCER_VALIDATION_STATUSES)[number];
+declare const CLAIM_ACTION_PERMISSIONS: readonly ["observe", "advise", "require-adjudication", "block", "not-established"];
+type ClaimActionPermission = (typeof CLAIM_ACTION_PERMISSIONS)[number];
+/**
+ * A producer validation reports how one evidence-producing method performed
+ * against a named, versioned corpus. A successful status without that
+ * referent would be an assertion about the producer rather than checkable
+ * validation evidence.
+ */
+type ProducerValidation = {
+    status: 'validated' | 'failed';
+    certification: {
+        id: string;
+        version: number;
+        corpus: string;
+    };
+} | {
+    status: 'not-evaluated' | 'not-applicable';
+    certification?: never;
+};
+/**
+ * One result family is a stable set of result values that share an evidence
+ * origin. A fixed binding applies one origin to the selected family. A
+ * result-field binding maps the producer's existing per-row provenance field
+ * into the public origin vocabulary without copying or flattening the rows.
+ */
+type ClaimFamilyOriginBinding = {
+    kind: 'fixed';
+    origin: Exclude<ClaimOrigin, 'mixed'>;
+} | {
+    kind: 'result-field';
+    field: string;
+    values: Readonly<Record<string, Exclude<ClaimOrigin, 'mixed'>>>;
+};
+interface ClaimFamilyContract {
+    id: string;
+    /** Repository-relative JSON path rooted at the command-owned result. */
+    selector: string;
+    origin: ClaimFamilyOriginBinding;
+}
+/**
+ * The descriptor-owned facts about a command's evidence producer. These facts
+ * identify production and input sources; they do not grant state authority or
+ * repository-policy permission.
+ */
+interface CommandClaimContract {
+    origin: ClaimOrigin;
+    observedSources: readonly ObservationSourceKind[];
+    producerValidation: ProducerValidation;
+    families?: readonly ClaimFamilyContract[];
+}
+interface ClaimCoverage {
+    state: ClaimCoverageState;
+    returned: number;
+    totalKnown: boolean;
+    total?: number;
+    omitted?: number;
+}
+interface RepositoryPolicyAction {
+    policyId: string;
+    policyVersion: typeof CLAIM_ACTION_POLICY_VERSION;
+    permission: ClaimActionPermission;
+    reasons: readonly string[];
+}
+/**
+ * A claim qualification is a set of independent facts that determine what one
+ * command result can support. Its real referents are the result's production
+ * method, enumeration extent, producer validation, observed repository state,
+ * and policy-permitted response. Keeping them independent is what prevents a
+ * strong fact in one dimension from silently strengthening another.
+ */
+interface ClaimQualificationV1 {
+    schemaVersion: typeof CLAIM_QUALIFICATION_SCHEMA_VERSION;
+    origin: ClaimOrigin;
+    coverage: ClaimCoverage;
+    producerValidation: ProducerValidation;
+    stateAuthority: DerivedObservationStateAuthority;
+    repositoryPolicy: RepositoryPolicyAction;
+    families?: readonly ClaimFamilyContract[];
+}
+interface ClaimCoverageInput {
+    complete: boolean | null;
+    totalKnown: boolean;
+    returned: number;
+    total?: number;
+    omitted?: number;
+}
+interface DeriveClaimQualificationInput {
+    contract: CommandClaimContract;
+    receipt: ObservationReceipt;
+    coverage?: ClaimCoverageInput;
+    repositoryPolicy?: RepositoryPolicyAction;
+}
+declare const DEFAULT_REPOSITORY_POLICY_ACTION: RepositoryPolicyAction;
+declare function deriveClaimQualification(input: DeriveClaimQualificationInput): ClaimQualificationV1;
+declare function deriveClaimCoverage(coverage: ClaimCoverageInput | undefined): ClaimCoverage;
+interface ClaimQualificationRequirements {
+    origins?: readonly ClaimOrigin[];
+    coverage?: readonly ClaimCoverageState[];
+    producerValidation?: readonly ProducerValidationStatus[];
+    stateAuthority?: readonly DerivedObservationStateAuthority['authority'][];
+    actionPermission?: readonly ClaimActionPermission[];
+}
+type ClaimQualificationPredicate = 'origin' | 'coverage' | 'producer-validation' | 'state-authority' | 'action-permission';
+interface ClaimQualificationPredicateResult {
+    predicate: ClaimQualificationPredicate;
+    satisfied: boolean;
+    required: readonly string[];
+    actual: string;
+}
+interface ClaimQualificationEvaluation {
+    satisfied: boolean;
+    predicates: readonly ClaimQualificationPredicateResult[];
+}
+/**
+ * Evaluate only predicates named by the consumer. This is the consumer-side
+ * contract: an omitted requirement grants nothing and a satisfied predicate
+ * cannot compensate for an unsatisfied one.
+ */
+declare function evaluateClaimQualification(qualification: ClaimQualificationV1, requirements: ClaimQualificationRequirements): ClaimQualificationEvaluation;
+declare function isClaimQualificationV1(value: unknown): value is ClaimQualificationV1;
+
 declare const CLI_JSON_ENVELOPE_KIND: "scip-query-result";
 declare const LEGACY_CLI_JSON_ENVELOPE_SCHEMA_VERSION: 0;
 declare const CURRENT_CLI_JSON_ENVELOPE_SCHEMA_VERSION: 1;
+declare const CLI_EVIDENCE_CONTEXT_SCHEMA_VERSION: 1;
+declare const CLI_ANALYSIS_MANIFEST_SCHEMA_VERSION: 1;
 interface CliJsonProducer {
     name: 'scip-query';
     version: string;
 }
+/**
+ * How one CLI result was produced and how much of the possible answer the
+ * invocation examined. These fields remain separate from the receipt because
+ * changing an analysis budget does not change which repository state was
+ * observed.
+ */
+interface CliAnalysisManifestV1 {
+    schemaVersion: typeof CLI_ANALYSIS_MANIFEST_SCHEMA_VERSION;
+    evidence?: 'graph-fact' | 'heuristic' | 'mixed';
+    analysisBudget?: unknown;
+    coverage?: unknown;
+    claimQualification?: ClaimQualificationV1;
+}
+/**
+ * The self-contained evidence carried by one repository-observation result.
+ * A version-1 receipt supplies local provenance; it does not by itself claim
+ * the fixed-snapshot and content relationships required for final completion.
+ */
+interface CliEvidenceContextV1 {
+    schemaVersion: typeof CLI_EVIDENCE_CONTEXT_SCHEMA_VERSION;
+    /** Optional only so evidence contexts written before operation roles remain readable. */
+    operationRole?: CommandOperationRole;
+    receipt: ObservationReceipt;
+    analysisManifest: CliAnalysisManifestV1;
+}
 /**
  * One public machine-readable CLI response. The envelope is the stable
  * transport contract; `result` remains the command-owned payload whose schema
@@ -212,14 +486,19 @@ interface CliJsonEnvelopeV1<Result = unknown> {
     schemaVersion: typeof CURRENT_CLI_JSON_ENVELOPE_SCHEMA_VERSION;
     producer: CliJsonProducer;
     command: string;
+    /** Optional only for additive compatibility with envelopes written before this field existed. */
+    operationRole?: CommandOperationRole;
     resultSchemaVersion: number;
     evidence?: 'graph-fact' | 'heuristic' | 'mixed';
     analysisBudget?: unknown;
     args: readonly unknown[];
     options: Readonly<Record<string, unknown>>;
     result: Result;
+    /** Present only when `result` is the bounded command-owned agent projection. */
+    resultProjection?: 'agent';
     coverage?: unknown;
     agentResult?: unknown;
+    evidenceContext?: CliEvidenceContextV1;
 }
 interface LegacyCliJsonEnvelope<Result = unknown> {
     command: string;
@@ -272,4 +551,4 @@ declare function requireCompatibleCliJsonEnvelope<Result = unknown>(input: unkno
  */
 declare function supportedCliResultSchemaVersions(command: string): readonly number[];
 
-export { CLI_JSON_ENVELOPE_KIND, CURRENT_CLI_JSON_ENVELOPE_SCHEMA_VERSION, type CliJsonEnvelopeV1, type CliJsonProducer, type CompatibleCliJsonEnvelope, type DecodedCliJsonEnvelope, LEGACY_CLI_JSON_ENVELOPE_SCHEMA_VERSION, type LegacyCliJsonEnvelope, type ReindexCancellationResult, type ReindexDiagnostics, type ReindexOperation, type ReindexRunRequest, type ReindexRunner, type ReindexRunnerOptions, type ReindexWorkerLaunch, type WatchClock, type WatchSubscription, type WatchSubscriptionFactory, type WatchSubscriptionOptions, Watcher, type WatcherOptions, type WatcherStopResult, createReindexRunner, decodeCliJsonEnvelope, initProjectConfig, installSkills, loadProjectConfig, requireCompatibleCliJsonEnvelope, resolveIndexStoragePaths, resolveReindexWorkerLaunch, supportedCliResultSchemaVersions };
+export { CLAIM_ACTION_PERMISSIONS, CLAIM_ACTION_POLICY_VERSION, CLAIM_COVERAGE_STATES, CLAIM_ORIGINS, CLAIM_QUALIFICATION_SCHEMA_VERSION, CLI_ANALYSIS_MANIFEST_SCHEMA_VERSION, CLI_EVIDENCE_CONTEXT_SCHEMA_VERSION, CLI_JSON_ENVELOPE_KIND, COMMAND_OPERATION_ROLES, CURRENT_CLI_JSON_ENVELOPE_SCHEMA_VERSION, type ClaimActionPermission, type ClaimCoverage, type ClaimCoverageInput, type ClaimCoverageState, type ClaimFamilyContract, type ClaimFamilyOriginBinding, type ClaimOrigin, type ClaimQualificationEvaluation, type ClaimQualificationPredicate, type ClaimQualificationPredicateResult, type ClaimQualificationRequirements, type ClaimQualificationV1, type CliAnalysisManifestV1, type CliEvidenceContextV1, type CliJsonEnvelopeV1, type CliJsonProducer, type CommandClaimContract, type CommandOperationInvocation, type CommandOperationRole, type CommandOperationRule, type CommandOperationRuleCondition, type CommandOperationSelector, type CompatibleCliJsonEnvelope, DEFAULT_REPOSITORY_POLICY_ACTION, type DecodedCliJsonEnvelope, type DeriveClaimQualificationInput, DerivedObservationStateAuthority, LEGACY_CLI_JSON_ENVELOPE_SCHEMA_VERSION, type LegacyCliJsonEnvelope, ObservationReceipt, ObservationSourceKind, PRODUCER_VALIDATION_STATUSES, type ProducerValidation, type ProducerValidationStatus, type ReindexCancellationResult, type ReindexCompletionContext, type ReindexDiagnostics, type ReindexOperation, type ReindexRunRequest, type ReindexRunner, type ReindexRunnerOptions, type ReindexWorkerLaunch, type RepositoryPolicyAction, type WatchClock, type WatchSubscription, type WatchSubscriptionFactory, type WatchSubscriptionOptions, Watcher, type WatcherOptions, type WatcherStopResult, commandOperation, commandOperationRoles, createReindexRunner, decodeCliJsonEnvelope, deriveClaimCoverage, deriveClaimQualification, evaluateClaimQualification, initProjectConfig, installSkills, isClaimQualificationV1, isCommandOperationRole, loadProjectConfig, operationObservesRepository, requireCompatibleCliJsonEnvelope, resolveCommandOperationRole, resolveIndexStoragePaths, resolveReindexWorkerLaunch, supportedCliResultSchemaVersions };