@quantiya/codevibe-core 2.0.0 → 2.0.1

package/dist/planner/client.d.ts

@@ -0,0 +1,103 @@
+import type { PlannerInput, PlannerDecision, PlannerProbeResult, Tier } from './types';
+import type { PlannerAdapter } from './adapter';
+import type { PlannerCacheLayer } from './cache';
+import type { PlannerHealthMachine } from './health-state';
+/**
+ * AppSync transport interface. Minimal shape so unit tests can inject
+ * a stub without mounting the full @quantiya/codevibe-core AppSyncClient.
+ */
+export interface PlannerAppSyncTransport {
+    classifyPlannerPrompt(input: {
+        sessionId: string;
+        prompt: string;
+        clarifications: string;
+        sessionContext: string;
+        budgetHint: string;
+    }): Promise<{
+        decision: string;
+        cacheHit: boolean;
+        cacheKind: string | null;
+        serverLatencyMs: number;
+        providerUsed: string;
+    }>;
+    pingPlanner(input: {
+        sessionId: string;
+    }): Promise<{
+        ok: boolean;
+        ms: number;
+    }>;
+}
+/**
+ * Crypto bridge — `encryptString` + `encryptJson` + `decryptJson`
+ * variants the adapter needs. Mirrors the existing
+ * codevibe-core CryptoService surface; injectable for tests.
+ */
+export interface PlannerCryptoBridge {
+    /** Encrypt a UTF-8 string to base64 AES-GCM ciphertext. */
+    encryptString(plaintext: string, sessionKeyB64: string): string;
+    /** Decrypt base64 AES-GCM → UTF-8 string. */
+    decryptString(ciphertextB64: string, sessionKeyB64: string): string;
+    /** Encrypt JSON-serializable value → base64 ciphertext. */
+    encryptJson(obj: unknown, sessionKeyB64: string): string;
+}
+export interface SessionKeyResolver {
+    getSessionKey(sessionId: string): Promise<string | null>;
+}
+export interface ShellEventEmit {
+    sessionId: string;
+    type: 'PLANNER_DECISION' | 'PLANNER_CACHE_HIT' | 'PLANNER_DEGRADED' | 'PLANNER_OUTAGE' | 'PLANNER_RECOVERED';
+    metadata?: Record<string, unknown>;
+}
+export type EmitShellEventFn = (args: ShellEventEmit) => Promise<void>;
+/**
+ * CP-1.b Stage 2 r2 M-3 — Typed errors that must NOT degrade health.
+ *
+ * The Lambda surfaces tier-gate / budget rejections as named-error
+ * GraphQL responses. Stage 2 r1's catch block recorded EVERY failure
+ * as a provider-health failure via `health.recordCall(elapsed, false)`,
+ * incorrectly driving the health machine toward Degraded/Outage on
+ * what are user-tier policy events (not provider outages). The
+ * client now classifies errors and ONLY records provider failures
+ * against health; tier/budget rejections emit NOTIFICATION events
+ * and throw without touching the machine.
+ */
+export declare class PlannerBudgetExceededError extends Error {
+    constructor(msg: string);
+}
+export declare class PlannerTierGateRejectedError extends Error {
+    constructor(msg: string);
+}
+export declare class BackendPlannerClient implements PlannerAdapter {
+    private transport;
+    private cache;
+    private health;
+    private crypto;
+    private sessionKeyResolver;
+    private emitShellEvent;
+    /** Shell-side tier-change detection (LOCK #30). */
+    lastClassifyTier: Tier | null;
+    /**
+     * CP-1.b Stage 2 r2 M-4 — Active session for probe(). The probe
+     * mutation requires a sessionId for ownership check; carrying the
+     * session in client state lets callers use the canonical
+     * `PlannerAdapter.probe()` contract. Set via `setActiveSession()`
+     * by orchestration-shell on session start.
+     */
+    private activeSessionId;
+    constructor(transport: PlannerAppSyncTransport, cache: PlannerCacheLayer, health: PlannerHealthMachine, crypto: PlannerCryptoBridge, sessionKeyResolver: SessionKeyResolver, emitShellEvent: EmitShellEventFn);
+    /**
+     * CP-1.b Stage 2 r2 M-4 — Set the active session ID used by
+     * `probe()`. Called by the orchestration-shell on session start
+     * (and cleared to `null` on session end).
+     */
+    setActiveSession(sessionId: string | null): void;
+    classify(input: PlannerInput): Promise<PlannerDecision>;
+    /**
+     * CP-1.b Stage 2 r2 M-4 — Honor the `PlannerAdapter.probe()`
+     * contract by reading the session from client state (set via
+     * `setActiveSession()`). Stage 2 r1 threw unconditionally and
+     * required callers to use the now-removed `probeWithSession()`
+     * method, which violated the adapter interface.
+     */
+    probe(): Promise<PlannerProbeResult>;
+}

package/dist/planner/health-state.d.ts

@@ -0,0 +1,24 @@
+import type { PlannerHealthState, PlannerHealthTransition } from './types';
+export type { PlannerHealthState, PlannerHealthTransition };
+export declare class PlannerHealthMachine {
+    private emitFn;
+    state: PlannerHealthState;
+    consecutiveFailures: number;
+    consecutiveSuccesses: number;
+    recentLatenciesMs: number[];
+    private readonly URGENT_FAILURE_FOR_DEGRADE;
+    private readonly P95_DEGRADE_THRESHOLD_MS;
+    private readonly P95_RECOVER_THRESHOLD_MS;
+    private readonly DEGRADED_TO_OUTAGE_FAILURES;
+    private readonly RECOVER_SUCCESSES_NEEDED;
+    private readonly RING_BUFFER_SIZE;
+    private readonly DEGRADED_PROBE_INTERVAL_MS;
+    private readonly OUTAGE_PROBE_INTERVAL_MS;
+    private lastProbeAt;
+    constructor(emitFn: (transition: PlannerHealthTransition) => void);
+    recordCall(latencyMs: number, success: boolean): PlannerHealthState;
+    shouldProbe(): boolean;
+    markProbeFired(): void;
+    private deriveNextState;
+    private p95Of;
+}

package/dist/planner/index.d.ts

@@ -0,0 +1,5 @@
+export * from './types';
+export * from './adapter';
+export { PlannerCacheLayer } from './cache';
+export { PlannerHealthMachine } from './health-state';
+export { BackendPlannerClient, PlannerBudgetExceededError, PlannerTierGateRejectedError, type PlannerAppSyncTransport, type PlannerCryptoBridge, type SessionKeyResolver, type ShellEventEmit, type EmitShellEventFn, } from './client';

package/dist/planner/types.d.ts

@@ -0,0 +1,113 @@
+import { z } from 'zod';
+export type Tier = 'FREE' | 'PRO' | 'MAX';
+export interface SessionContext {
+    sessionId: string;
+    userId: string;
+    tier: Tier;
+    currentTaskState: 'none' | 'in_progress' | 'awaiting_user' | 'awaiting_review' | 'merge_gate_pending';
+    structuralSummaryDigest: string;
+    recentEventCount: number;
+}
+export declare const SessionContextSchema: z.ZodObject<{
+    sessionId: z.ZodString;
+    userId: z.ZodString;
+    tier: z.ZodEnum<["FREE", "PRO", "MAX"]>;
+    currentTaskState: z.ZodEnum<["none", "in_progress", "awaiting_user", "awaiting_review", "merge_gate_pending"]>;
+    structuralSummaryDigest: z.ZodString;
+    recentEventCount: z.ZodNumber;
+}, "strip", z.ZodTypeAny, {
+    sessionId: string;
+    userId: string;
+    structuralSummaryDigest: string;
+    tier: "FREE" | "PRO" | "MAX";
+    currentTaskState: "none" | "merge_gate_pending" | "in_progress" | "awaiting_user" | "awaiting_review";
+    recentEventCount: number;
+}, {
+    sessionId: string;
+    userId: string;
+    structuralSummaryDigest: string;
+    tier: "FREE" | "PRO" | "MAX";
+    currentTaskState: "none" | "merge_gate_pending" | "in_progress" | "awaiting_user" | "awaiting_review";
+    recentEventCount: number;
+}>;
+export interface BudgetHint {
+    wallClockMsRemaining: number;
+    reviseAttempts: number;
+}
+export declare const BudgetHintSchema: z.ZodObject<{
+    wallClockMsRemaining: z.ZodNumber;
+    reviseAttempts: z.ZodNumber;
+}, "strip", z.ZodTypeAny, {
+    wallClockMsRemaining: number;
+    reviseAttempts: number;
+}, {
+    wallClockMsRemaining: number;
+    reviseAttempts: number;
+}>;
+export interface Clarification {
+    question: string;
+    answer: string;
+}
+export declare const ClarificationSchema: z.ZodObject<{
+    question: z.ZodString;
+    answer: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    question: string;
+    answer: string;
+}, {
+    question: string;
+    answer: string;
+}>;
+export interface PlannerInput {
+    prompt: string;
+    clarifications: Clarification[];
+    sessionContext: SessionContext;
+    budgetHint: BudgetHint;
+}
+export interface PlannerDecision {
+    action: 'start_task' | 'summarize_current_status' | 'advisory_response' | 'ask_user' | 'refuse';
+    rationale: string;
+    clarifying_question?: string;
+    advisory_summary?: string;
+    /** Opaque per parent §6 lines 967-972; CP-1 NEVER inspects fields. */
+    gateRequest?: Record<string, unknown>;
+}
+export declare const PlannerDecisionSchema: z.ZodObject<{
+    action: z.ZodEnum<["start_task", "summarize_current_status", "advisory_response", "ask_user", "refuse"]>;
+    rationale: z.ZodString;
+    clarifying_question: z.ZodOptional<z.ZodString>;
+    advisory_summary: z.ZodOptional<z.ZodString>;
+    gateRequest: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+}, "strip", z.ZodTypeAny, {
+    action: "start_task" | "summarize_current_status" | "advisory_response" | "ask_user" | "refuse";
+    rationale: string;
+    clarifying_question?: string | undefined;
+    advisory_summary?: string | undefined;
+    gateRequest?: Record<string, unknown> | undefined;
+}, {
+    action: "start_task" | "summarize_current_status" | "advisory_response" | "ask_user" | "refuse";
+    rationale: string;
+    clarifying_question?: string | undefined;
+    advisory_summary?: string | undefined;
+    gateRequest?: Record<string, unknown> | undefined;
+}>;
+export interface PlannerProbeResult {
+    ok: boolean;
+    latencyMs: number;
+    errorClass?: 'timeout' | 'rate_limited' | 'unreachable' | 'malformed_response' | 'auth_failed';
+}
+export type ClassificationKind = 'workflow_status_query' | 'workflow_audit_query' | 'workflow_review_query' | 'workflow_continuation_query' | 'advisory_response_safe' | 'ask_user_clarification';
+export interface CachedClassification {
+    kind: ClassificationKind;
+    clarifyingQuestion?: string;
+    advisorySummary?: string;
+}
+export type PlannerHealthState = 'Available' | 'Degraded' | 'Outage';
+export interface PlannerHealthTransition {
+    newState: PlannerHealthState;
+    fromState: PlannerHealthState;
+    reason: string;
+    consecutiveFailures: number;
+    consecutiveSuccesses: number;
+    p95Ms: number;
+}

package/dist/session/__tests__/session-resume-service-keys.test.d.ts

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

package/dist/session/session-rekey.d.ts

@@ -36,3 +36,43 @@ export interface RekeyOptions {
  * @returns The number of new grants that succeeded.
  */
 export declare function rekeySessionForNewDevices(sessionId: string, sessionKey: string, appSyncClient: AppSyncClient, options?: RekeyOptions): Promise<number>;
+/**
+ * Options for {@link awaitOwnSessionKeyGrant}.
+ */
+export interface AwaitOwnGrantOptions {
+    /** Poll interval in ms. Default 5000. */
+    pollIntervalMs?: number;
+    /** Max poll attempts. Default 6 (30s total at 5s intervals). */
+    maxAttempts?: number;
+    /** Authenticated AppSyncClient. */
+    appSyncClient: AppSyncClient;
+    /** Fired on successful decrypt. Telemetry-only — never thrown. */
+    onSuccess?: (attemptCount: number) => void;
+    /** Fired after maxAttempts exhausted. Telemetry-only — never thrown. */
+    onTimeout?: (attemptCount: number) => void;
+}
+/**
+ * Wait for this device's deviceId to appear in `session.encryptedKeys`.
+ *
+ * Triggered when {@link keychainManager.getSessionKey} returned null on
+ * resume AND at least one other device IS in encryptedKeys (so some other
+ * device can mint a grant for us via grantSessionKey). Caller must have
+ * already invoked {@link registerDeviceEncryptionKey} BEFORE this helper —
+ * that's what causes mobile's DeviceKeyWatcher subscription to fire and
+ * grant the session key to our (possibly rotated) pubKey.
+ *
+ * This helper deliberately bypasses {@link keychainManager.getSessionKey}
+ * (which has a cache short-circuit) and instead:
+ *   1. Calls {@link AppSyncClient.getSession} each poll for fresh
+ *      `encryptedKeys`.
+ *   2. Looks for our `deviceId` in the fresh list.
+ *   3. If found, calls {@link cryptoService.decryptSessionKey} directly.
+ *   4. On success, populates the keychain cache (so subsequent
+ *      `getSessionKey` calls hit the cache). The cache is NEVER populated
+ *      on failure — there's no null sentinel.
+ *
+ * Returns the decrypted session key on success, or `null` after timeout.
+ * Errors are swallowed inside the loop (best-effort polling); telemetry
+ * surfaces success vs timeout via the optional callbacks.
+ */
+export declare function awaitOwnSessionKeyGrant(sessionId: string, options: AwaitOwnGrantOptions): Promise<string | null>;

package/dist/session/session-resume.d.ts

@@ -24,6 +24,30 @@ export interface ResumeOrCreateSessionResult {
     /** The E2E session key (for encrypting/decrypting events), or null if no encryption */
     sessionKey: string | null;
 }
+/**
+ * CP-1.b IMPL r5 H-2 — Typed error thrown by `prepareSessionEncryption()`
+ * when `listServiceDeviceKeys()` returns an empty array across all
+ * attempts. Contract per r6/r7 fix: 4 fetch attempts, 3 backoff sleeps:
+ * 1s/2s/4s (total ~7s wall on full-failure path). Per CP-1.b design
+ * §6.1 lifecycle bullet "Fail-safe:
+ * shell-side createSession retries with 1s + 2s + 4s backoff" + LOCK
+ * #32 (prewarm custom-resource closes the first-cold-start window
+ * structurally; this retry is the disaster-recovery fail-safe).
+ *
+ * Surfacing this as a typed error (rather than the previous
+ * best-effort behavior which built sessions WITHOUT the planner-proxy
+ * grant — guaranteeing every subsequent Lambda decrypt would fail)
+ * lets the plugin / CLI wrappers display an actionable banner to the
+ * user instead of producing a half-broken session.
+ *
+ * The Lambda emits a matching `PlannerProxyServiceKeyMissing`
+ * CloudWatch metric in its `handleClassify` decrypt-failure path; the
+ * shell-side typed error closes the funnel at session-create time so
+ * the user never reaches a session that can't be decrypted.
+ */
+export declare class PlannerProxyServiceKeyMissingError extends Error {
+    constructor(msg: string);
+}
 /**
  * Prepare E2E encryption for a new session.
  *
@@ -36,6 +60,7 @@ export interface ResumeOrCreateSessionResult {
 export declare function prepareSessionEncryption(sessionId: string, appSyncClient: AppSyncClient, logger: Logger): Promise<{
     sessionKey: string;
     encryptedKeys: EncryptedSessionKey[];
+    skippedDeviceIds: string[];
 } | null>;
 /**
  * Resume an existing session or create a new one.

package/dist/structural-summary/__tests__/__fixtures__/fixture-helpers.d.ts

@@ -0,0 +1,11 @@
+export declare function makeTmpDir(prefix?: string): Promise<string>;
+export declare function git(cwd: string, ...args: string[]): Promise<string>;
+export declare function writeFile(file: string, content: string): Promise<void>;
+/**
+ * Initialises a git repo at `dir`, commits initial empty-tree marker so
+ * `git status --porcelain` works.
+ */
+export declare function initGitRepo(dir: string): Promise<void>;
+export declare function gitAdd(cwd: string, file: string): Promise<void>;
+export declare function gitCommit(cwd: string, msg?: string): Promise<void>;
+export declare function cleanup(dir: string): Promise<void>;

package/dist/structural-summary/__tests__/assembler.test.d.ts

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

package/dist/structural-summary/__tests__/generator.test.d.ts

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

package/dist/structural-summary/__tests__/language-detect.test.d.ts

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

package/dist/structural-summary/__tests__/manifest-parsers/cargo.test.d.ts

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

package/dist/structural-summary/__tests__/manifest-parsers/gomod.test.d.ts

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

package/dist/structural-summary/__tests__/manifest-parsers/gradle.test.d.ts

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

package/dist/structural-summary/__tests__/manifest-parsers/index.test.d.ts

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

package/dist/structural-summary/__tests__/manifest-parsers/npm.test.d.ts

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

package/dist/structural-summary/__tests__/manifest-parsers/podfile.test.d.ts

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

package/dist/structural-summary/__tests__/manifest-parsers/pyproject.test.d.ts

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

package/dist/structural-summary/__tests__/opt-in-store.test.d.ts

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

package/dist/structural-summary/__tests__/privacy-filter.test.d.ts

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

package/dist/structural-summary/__tests__/safe-file-read.test.d.ts

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

package/dist/structural-summary/__tests__/user-ignore-matcher.test.d.ts

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

package/dist/structural-summary/__tests__/walker.test.d.ts

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

package/dist/structural-summary/generator.d.ts

@@ -0,0 +1,8 @@
+import { type ExclusionState, type StructuralSummaryGenerator } from './types';
+export declare function createStructuralSummaryGenerator(): StructuralSummaryGenerator;
+export interface ReadmeCounters {
+    excludedAsUntracked: number;
+    excludedByGitignore: number;
+    excludedByIgnoreFile: number;
+}
+export declare function readReadmePreview(rootPath: string, exclusionState: ExclusionState, countedExactPaths: Set<string>, countedPrunedPrefixes: Set<string>, counters: ReadmeCounters): Promise<string>;

package/dist/structural-summary/index.d.ts

@@ -0,0 +1,7 @@
+export { createStructuralSummaryGenerator, readReadmePreview, } from './generator';
+export { walk as walkRepoTree } from './walker';
+export { isPathAdmissible, isPathInIgnoredPrefixes, isPathAccountedFor, matchesSecretDenyList, SECRET_DENY_LIST, } from './privacy-filter';
+export { readOptIn, addBodyPath, removeBodyPath, optInFilePath, } from './opt-in-store';
+export { compileUserIgnore, emptyUserIgnoreMatcher, } from './user-ignore-matcher';
+export type { DirectoryNode, RepoSummary, StructuralSummary, StructuralSummaryGenerator, GenerateOpts, PrivacyEnvelope, WalkResult, ExclusionState, UserIgnoreMatcher, ParsedManifest, ManifestType, OptInFile, StructuralSummaryErrorKind, } from './types';
+export { StructuralSummaryError } from './types';

package/dist/structural-summary/manifest-parsers/cargo.d.ts

@@ -0,0 +1,3 @@
+import { type ParsedManifest } from '../types';
+export declare function findManifest(rootPath: string): Promise<string | null>;
+export declare function parse(file: string): Promise<ParsedManifest>;

package/dist/structural-summary/manifest-parsers/index.d.ts

@@ -0,0 +1,7 @@
+import type { ExclusionState, ParsedManifest } from '../types';
+export interface ManifestCounters {
+    excludedAsUntracked: number;
+    excludedByGitignore: number;
+    excludedByIgnoreFile: number;
+}
+export declare function parse(rootPath: string, exclusionState: ExclusionState, countedExactPaths: Set<string>, countedPrunedPrefixes: Set<string>, counters: ManifestCounters): Promise<ParsedManifest>;

package/dist/structural-summary/manifest-parsers/npm.d.ts

@@ -0,0 +1,3 @@
+import { type ParsedManifest } from '../types';
+export declare function findManifest(rootPath: string): Promise<string | null>;
+export declare function parse(file: string): Promise<ParsedManifest>;

package/dist/structural-summary/manifest-parsers/other.d.ts

@@ -0,0 +1,17 @@
+import { type ParsedManifest } from '../types';
+export declare const pyproject: {
+    findManifest(rootPath: string): Promise<string | null>;
+    parse(file: string): Promise<ParsedManifest>;
+};
+export declare const gomod: {
+    findManifest(rootPath: string): Promise<string | null>;
+    parse(file: string): Promise<ParsedManifest>;
+};
+export declare const podfile: {
+    findManifest(rootPath: string): Promise<string | null>;
+    parse(file: string): Promise<ParsedManifest>;
+};
+export declare const gradle: {
+    findManifest(rootPath: string): Promise<string | null>;
+    parse(file: string): Promise<ParsedManifest>;
+};

package/dist/structural-summary/opt-in-store.d.ts

@@ -0,0 +1,24 @@
+import { type OptInFile } from './types';
+import type { Tier } from '../orchestration-shell/types';
+export declare function optInFilePath(): string;
+/**
+ * Per Stage 2 r1 Gemini M-1: reader takes `currentTier`. If
+ * `parsed.tierAtOptIn !== currentTier`, returns `null` (graceful tier-
+ * downgrade invalidation — no error throw).
+ */
+export declare function readOptIn(currentTier: Tier): Promise<OptInFile | null>;
+/**
+ * Per Stage 2 r1 Gemini H-3 option (a): widen to `Tier` so callers can
+ * pass `args.tier` directly without an unsafe type narrow. Runtime gate
+ * inside the function is authoritative; non-MAX throws `tier_gate`.
+ *
+ * Stage 2 r2 fix (H-1, Codex): validates that `bodyPath` is absolute
+ * BEFORE any persistence work. Normalises via `path.resolve()`
+ * (defense-in-depth — strips any residual `..` segments) and resolves
+ * symlinks via `fs.realpath()`. The realpath result is what gets
+ * persisted, so a future `cd` that lands the user in a different repo
+ * cannot trip a relative-path match. Throws `StructuralSummaryError(
+ * 'invalid_path')` for non-absolute or unresolvable inputs.
+ */
+export declare function addBodyPath(bodyPath: string, currentTier: Tier): Promise<OptInFile>;
+export declare function removeBodyPath(bodyPath: string): Promise<OptInFile>;

package/dist/structural-summary/privacy-filter.d.ts

@@ -0,0 +1,110 @@
+import type { ExclusionState } from './types';
+/**
+ * Stage 2 IMPL r2 fix (H-3, Codex H-2): strict path-containment helper.
+ *
+ * Returns true iff `rel` (the output of `path.relative(root, target)`)
+ * denotes a path OUTSIDE `root` via parent-directory traversal. Required
+ * because the naive `rel.startsWith('..')` form falsely classifies valid
+ * child names that happen to BEGIN with `..` (e.g., `..scratch/file.ts`,
+ * `..hidden`, `..foo/bar`) as outside the root.
+ *
+ * Correct semantics:
+ *   rel === '..'                       → outside (parent of root)
+ *   rel === '..' + path.sep + 'sib'    → outside (sibling of root)
+ *   rel === '..' + '/' + 'sib'         → outside (POSIX form, used by
+ *                                        git output / forward-slash
+ *                                        callers on Windows)
+ *   rel === '..foo'                    → INSIDE (child whose name
+ *                                        starts with `..`)
+ *
+ * Used in: walker.ts `buildExclusionState` (realRootPath outside-repo
+ * check + untracked subtree filter) and privacy-filter.ts
+ * `isPathAdmissible` (relative-to-realRootPath admission).
+ */
+export declare function isOutsideRoot(rel: string): boolean;
+/**
+ * Static secret-file deny-list. Matches `.env`, `.env.*`, `.aws/credentials`,
+ * and assorted private-key formats. Matched against absolute-path basename
+ * and a few suffix patterns. Per §4.3 step 2 first match.
+ */
+export declare const SECRET_DENY_LIST: readonly string[];
+/**
+ * Pure path test — returns true if `absolutePath` matches any secret
+ * deny-list pattern. The walker uses this to skip secret files silently
+ * (no counter increment per §4.3 hard-caps audit-quality note).
+ */
+export declare function matchesSecretDenyList(absolutePath: string): boolean;
+/**
+ * Helper exported alongside `isPathAdmissible`: returns true if
+ * `absolutePath` is either:
+ *   (a) an exact entry in `exactPaths` — file-level gitignore match,
+ *       O(1) `Set.has(p)`; OR
+ *   (b) equal to OR a descendant of an entry in `dirPrefixes` —
+ *       directory-level gitignore match, implemented via check-then-step
+ *       ancestor-walk:
+ *
+ *       let p = absolutePath;
+ *       while (true) {
+ *         if (dirPrefixes.has(p)) return true;
+ *         const parent = path.dirname(p);
+ *         if (parent === p) return false;   // filesystem root reached
+ *         p = parent;
+ *       }
+ *
+ * Key properties (per round-7 revision Codex r6 H-1 + Gemini r6 H-1/M-2):
+ *
+ *   1. **Signature is 3-arg** `(absolutePath, exactPaths, dirPrefixes)`.
+ *      The helper does NOT receive `realRootPath`. The walk MUST proceed
+ *      past `realRootPath` because `git ls-files --directory` may report
+ *      an ignored ancestor ABOVE the launch root (e.g., parent
+ *      `.gitignore` ignores `sub/` when launch root is `repo/sub/inner`).
+ *   2. **Check-then-step semantics**: check `dirPrefixes.has(p)` BEFORE
+ *      advancing `p`. This handles the case where `absolutePath` is
+ *      itself an entry in `dirPrefixes` (e.g., Step 0.5 root admission
+ *      tests `realRootPath` directly when it is itself ignored).
+ *   3. **Loop termination**: when `path.dirname(p) === p` (POSIX `/`,
+ *      Windows `C:\`). NO early termination at `realRootPath`.
+ *
+ * Lookup cost is O(absolute filesystem depth) (typically <30 on any sane
+ * mount tree), independent of `|dirPrefixes|`.
+ */
+export declare function isPathInIgnoredPrefixes(absolutePath: string, exactPaths: Set<string>, dirPrefixes: Set<string>): boolean;
+/**
+ * INTERNAL helper (not exported from the module index, but exported here
+ * so the manifest dispatcher + README reader can import it). Returns true
+ * iff `realFile` is already accounted for in the walker's two-set ledger
+ * (exact match OR equal-to-or-descendant-of an entry in pruned prefixes).
+ *
+ * Same canonical algorithm as `isPathInIgnoredPrefixes` — 3-arg signature,
+ * check-then-step, filesystem-root termination. Per round-7 revision
+ * Gemini r6 M-1 + Codex r6 H-1 + Gemini r6 M-2.
+ */
+export declare function isPathAccountedFor(realFile: string, countedExactPaths: Set<string>, countedPrunedPrefixes: Set<string>): boolean;
+/**
+ * Order of checks (mirrors §4.3 step 2, first match wins):
+ *   1. secret (deny-list path-glob match — operates on basename + suffix).
+ *   2. untracked (`state.untrackedSet.has(absolutePath)`; SKIPPED if
+ *      notInGitRepo).
+ *   3. gitignore (`isPathInIgnoredPrefixes(...)`; SKIPPED if notInGitRepo).
+ *   4. userIgnore (`state.userIgnoreMatcher.ignores(path.relative(
+ *      realRootPath, absolutePath), isDir)`).
+ *
+ * Pure in-memory check; consults only the pre-built `state`. No I/O.
+ *
+ * `isDir` (Stage 2 r2 fix, M-2 Gemini M-1): walker passes
+ * `entry.isDirectory()` here. File-only callers (manifest dispatcher,
+ * README reader) accept the default `false`. The flag is consumed by
+ * `userIgnoreMatcher.ignores()` to honour trailing-slash `dir/` rules.
+ *
+ * Caller is responsible for incrementing the appropriate counter on
+ * `privacyEnvelope` when `admissible === false` (so audit signal is
+ * preserved). `reason === 'secret'` is silent (no counter — per §4.3
+ * hard-caps audit-quality note).
+ */
+export declare function isPathAdmissible(absolutePath: string, state: ExclusionState, isDir?: boolean): {
+    admissible: true;
+} | {
+    admissible: false;
+    reason: 'secret' | 'untracked' | 'gitignore' | 'userIgnore';
+};
+export type { ExclusionState } from './types';

package/dist/structural-summary/safe-file-read.d.ts

@@ -0,0 +1,11 @@
+/**
+ * TOCTOU-safe text file read. Returns the file contents as UTF-8 or
+ * `null` on any refusal / error. See module JSDoc for the syscall
+ * sequence + threat model.
+ *
+ * @param absPath Absolute filesystem path. Caller is responsible for
+ *                path absolutism + admission-oracle checks BEFORE
+ *                invoking this function; this helper only guards the
+ *                lstat→open transition.
+ */
+export declare function safeReadTextFile(absPath: string): Promise<string | null>;