@hcu-lab.me/mcp-device 1.0.9 → 1.0.12

package/dist/context/service.d.ts

@@ -0,0 +1,278 @@
+import { type GatedFeature } from './authorization.js';
+export { isFeatureAuthorized, SOC_PUBLIC_KEY } from './authorization.js';
+import { type GraphOptions } from './graph.js';
+import { ContextStore } from './store.js';
+import { type SearchOptions, type ReadOptions } from './search.js';
+export declare const FEATURE_LIVE_CAPTURE = false;
+export declare const FEATURE_PUBLIC_GATEWAY = false;
+export interface ContextServiceOptions {
+    FEATURE_LIVE_CAPTURE?: boolean;
+    FEATURE_PUBLIC_GATEWAY?: boolean;
+}
+/** Explicit foreground ownership only; no timers, scheduler, sync or source scans. */
+export declare class ContextService {
+    private readonly store;
+    private readonly options;
+    private readonly jobs;
+    private readonly gaps;
+    constructor(store: ContextStore, options?: ContextServiceOptions);
+    /** All future Phase 7/8 tool initialization must pass this fail-closed boundary.
+     * No capture hooks, public routes or MCP tools are enabled by this change. */
+    initializeFeature(feature: GatedFeature): void;
+    requireFeatureAuthorized(feature: GatedFeature): void;
+    /** Revalidate synchronously immediately before the side effect. Revocation
+     * takes effect on the next call; this is not cancellation of in-flight work. */
+    executeFeature<T>(feature: GatedFeature, action: () => T): T;
+    graph(owner: string, repo: string, input: GraphOptions): {
+        schema_version: number;
+        ok: boolean;
+        scope: {
+            repository_ref: string;
+        };
+        index: {
+            generation: number;
+            indexed_through_event: number;
+            manifest_hash: string | number | bigint | Uint8Array<ArrayBufferLike> | null;
+            pending_events: number;
+            unknown_events: number;
+            fts_documents: number;
+        };
+        coverage: {
+            complete: boolean;
+            reasons: string[];
+        };
+        nodes: import("./graph.js").ActivityNode[];
+        edges: import("./graph.js").ActivityEdge[];
+        partial: boolean;
+        next_cursor: null;
+        visited_nodes: number;
+        examined_edges: number;
+        returned_nodes: number;
+        truncated_by: string[];
+        path: string[];
+    };
+    search(owner: string, repo: string, input: SearchOptions): {
+        schema_version: number;
+        ok: boolean;
+        scope: {
+            repository_ref: string;
+        };
+        index: {
+            generation: number | null;
+            indexed_through_event: number;
+            pending_events: number;
+            freshness: string;
+        };
+        coverage: {
+            complete: boolean;
+            reasons: string[];
+        };
+        items: Record<string, unknown>[];
+        partial: boolean;
+        next_cursor: string | null;
+        warnings: string[];
+    };
+    read(owner: string, repo: string, input: ReadOptions): {
+        schema_version: number;
+        ok: boolean;
+        scope: {
+            repository_ref: string;
+        };
+        index: {
+            generation: number | null;
+            indexed_through_event: number;
+            pending_events: number;
+            freshness: string;
+        };
+        coverage: {
+            complete: boolean;
+            reasons: string[];
+        };
+        items: Record<string, unknown>[];
+        partial: boolean;
+        next_cursor: string | null;
+        warnings: string[];
+    };
+    sync(owner: string, repo: string): {
+        indexed: number;
+        schema_version: number;
+        ok: boolean;
+        scope: {
+            repository_ref: string;
+        };
+        index: {
+            generation: number | null;
+            indexed_through_event: number;
+            pending_events: number;
+            fts_documents: number;
+            freshness: string;
+        };
+        coverage: {
+            complete: boolean;
+            reasons: string[];
+        };
+        capture_health: {
+            capture_healthy: boolean;
+            in_memory_gaps: number;
+            unknown_after_restart: number;
+            quota_gaps: number;
+        };
+        active_jobs: {
+            job_ref: string;
+            action: "sync" | "rebuild";
+            started_at: number;
+        }[];
+        storage: {
+            available: boolean;
+            accounted_bytes: number;
+            accounting: string;
+            quota_enforced: boolean;
+        };
+        wiki_enabled: boolean;
+    };
+    rebuild(owner: string, repo: string): {
+        indexed: number;
+        schema_version: number;
+        ok: boolean;
+        scope: {
+            repository_ref: string;
+        };
+        index: {
+            generation: number | null;
+            indexed_through_event: number;
+            pending_events: number;
+            fts_documents: number;
+            freshness: string;
+        };
+        coverage: {
+            complete: boolean;
+            reasons: string[];
+        };
+        capture_health: {
+            capture_healthy: boolean;
+            in_memory_gaps: number;
+            unknown_after_restart: number;
+            quota_gaps: number;
+        };
+        active_jobs: {
+            job_ref: string;
+            action: "sync" | "rebuild";
+            started_at: number;
+        }[];
+        storage: {
+            available: boolean;
+            accounted_bytes: number;
+            accounting: string;
+            quota_enforced: boolean;
+        };
+        wiki_enabled: boolean;
+    };
+    checkpoint(owner: string, repo: string, input: {
+        repository_root: string;
+        worktree_ref: string;
+        summary?: string;
+        evidence_refs?: string[];
+    }): {
+        checkpoint: {
+            observed: {
+                head: string;
+                worktree_ref: string;
+                dirty: boolean;
+                changed_paths: string[];
+            };
+            reported: {
+                summary: string;
+                evidence_refs: string[];
+            };
+            ref: string;
+        };
+        schema_version: number;
+        ok: boolean;
+        scope: {
+            repository_ref: string;
+        };
+        index: {
+            generation: number | null;
+            indexed_through_event: number;
+            pending_events: number;
+            fts_documents: number;
+            freshness: string;
+        };
+        coverage: {
+            complete: boolean;
+            reasons: string[];
+        };
+        capture_health: {
+            capture_healthy: boolean;
+            in_memory_gaps: number;
+            unknown_after_restart: number;
+            quota_gaps: number;
+        };
+        active_jobs: {
+            job_ref: string;
+            action: "sync" | "rebuild";
+            started_at: number;
+        }[];
+        storage: {
+            available: boolean;
+            accounted_bytes: number;
+            accounting: string;
+            quota_enforced: boolean;
+        };
+        wiki_enabled: boolean;
+    };
+    /** Trusted local admin seam, intentionally absent from CLI/MCP agent action dispatch. */
+    cleanup(owner: string, repo: string, input: {
+        before: number;
+        localAdmin: boolean;
+    }): {
+        purged: number;
+        accounted_bytes: number;
+    };
+    captureGap(owner: string, repo: string, reason: string): void;
+    /** Trusted observer scope only; works even when the storage connection is down. */
+    recordGap(owner: string, repo: string, reason: string): void;
+    status(owner: string, repo: string): {
+        schema_version: number;
+        ok: boolean;
+        scope: {
+            repository_ref: string;
+        };
+        index: {
+            generation: number | null;
+            indexed_through_event: number;
+            pending_events: number;
+            fts_documents: number;
+            freshness: string;
+        };
+        coverage: {
+            complete: boolean;
+            reasons: string[];
+        };
+        capture_health: {
+            capture_healthy: boolean;
+            in_memory_gaps: number;
+            unknown_after_restart: number;
+            quota_gaps: number;
+        };
+        active_jobs: {
+            job_ref: string;
+            action: "sync" | "rebuild";
+            started_at: number;
+        }[];
+        storage: {
+            available: boolean;
+            accounted_bytes: number;
+            accounting: string;
+            quota_enforced: boolean;
+        };
+        wiki_enabled: boolean;
+    };
+    startJob(owner: string, repo: string, action: 'sync' | 'rebuild'): string;
+    /** Foreground work completes before another request can run; cancel only releases a scoped pending job. */
+    cancel(owner: string, repo: string, id: string): {
+        job_ref: string;
+        state: "cancelled";
+    };
+    finishJob(owner: string, repo: string, id: string): void;
+}

package/dist/context/service.js

@@ -0,0 +1,160 @@
+import { randomBytes, createHash } from 'node:crypto';
+import { requireFeatureAuthorized, GATE_ERROR } from './authorization.js';
+export { isFeatureAuthorized, SOC_PUBLIC_KEY } from './authorization.js';
+import { queryActivityGraph } from './graph.js';
+import { execFileSync } from 'node:child_process';
+import { realpathSync } from 'node:fs';
+import { sync } from './indexer.js';
+import { search, readEvidence } from './search.js';
+export const FEATURE_LIVE_CAPTURE = false;
+export const FEATURE_PUBLIC_GATEWAY = false;
+const GAP_REASONS = new Set(['storage_unavailable', 'busy', 'quota', 'outcome_failed']);
+/** Explicit foreground ownership only; no timers, scheduler, sync or source scans. */
+export class ContextService {
+    constructor(store, options = {}) {
+        this.store = store;
+        this.options = options;
+        this.jobs = new Map();
+        this.gaps = new Map();
+        for (const feature of ['FEATURE_LIVE_CAPTURE', 'FEATURE_PUBLIC_GATEWAY']) {
+            if (options[feature] === true)
+                this.initializeFeature(feature);
+        }
+    }
+    /** All future Phase 7/8 tool initialization must pass this fail-closed boundary.
+     * No capture hooks, public routes or MCP tools are enabled by this change. */
+    initializeFeature(feature) {
+        this.requireFeatureAuthorized(feature);
+    }
+    requireFeatureAuthorized(feature) {
+        if (this.options[feature] !== true)
+            throw new Error(GATE_ERROR);
+        requireFeatureAuthorized(feature);
+    }
+    /** Revalidate synchronously immediately before the side effect. Revocation
+     * takes effect on the next call; this is not cancellation of in-flight work. */
+    executeFeature(feature, action) {
+        this.requireFeatureAuthorized(feature);
+        return action();
+    }
+    graph(owner, repo, input) { return queryActivityGraph(this.store, owner, repo, input); }
+    search(owner, repo, input) { return search(this.store, owner, repo, input); }
+    read(owner, repo, input) { return readEvidence(this.store, owner, repo, input); }
+    sync(owner, repo) {
+        this.store.authorize(owner, repo);
+        this.store.reconcileQuota();
+        const job = this.startJob(owner, repo, 'sync');
+        try {
+            const result = sync(this.store, owner, repo);
+            return { ...this.status(owner, repo), indexed: result.indexed };
+        }
+        finally {
+            this.finishJob(owner, repo, job);
+        }
+    }
+    rebuild(owner, repo) {
+        const job = this.startJob(owner, repo, 'rebuild');
+        try {
+            const result = sync(this.store, owner, repo, { rebuild: true });
+            return { ...this.status(owner, repo), indexed: result.indexed };
+        }
+        finally {
+            this.finishJob(owner, repo, job);
+        }
+    }
+    checkpoint(owner, repo, input) {
+        this.store.authorize(owner, repo);
+        const refs = input.evidence_refs ?? [];
+        if (refs.length > 20 || (input.summary !== undefined && (typeof input.summary !== 'string' || Buffer.byteLength(input.summary) > 4096)))
+            throw new Error('BUDGET_EXCEEDED');
+        for (const ref of refs)
+            this.store.read(owner, repo, ref);
+        const git = (...args) => execFileSync('git', ['-C', input.repository_root, ...args], {
+            encoding: 'utf8', timeout: 5000, maxBuffer: 65536, stdio: ['ignore', 'pipe', 'pipe'],
+            env: { ...process.env, GIT_DIR: undefined, GIT_WORK_TREE: undefined, GIT_COMMON_DIR: undefined },
+        }).trim();
+        const common = git('rev-parse', '--path-format=absolute', '--git-common-dir');
+        const identity = createHash('sha256').update(realpathSync(common)).digest('hex');
+        const worktree = createHash('sha256').update(realpathSync(git('rev-parse', '--show-toplevel'))).digest('hex');
+        if (this.store.findRepository(owner, identity) !== repo || worktree !== input.worktree_ref)
+            throw new Error('ACCESS_DENIED');
+        const status = git('status', '--porcelain=v1', '-z');
+        const checkpoint = {
+            observed: { head: git('rev-parse', 'HEAD'), worktree_ref: worktree, dirty: status.length > 0,
+                changed_paths: status.split('\0').filter(Boolean).map(line => this.store.redactPayload(line.slice(3)).text).slice(0, 256) },
+            reported: { summary: this.store.redactPayload(input.summary ?? '').text, evidence_refs: refs },
+        };
+        const ref = this.store.append(owner, repo, JSON.stringify(checkpoint), { checkpoint: true });
+        const retained = JSON.parse(String(this.store.read(owner, repo, ref).text));
+        return { ...this.status(owner, repo), checkpoint: { ref, ...retained } };
+    }
+    /** Trusted local admin seam, intentionally absent from CLI/MCP agent action dispatch. */
+    cleanup(owner, repo, input) {
+        if ([...this.jobs.values()].some(job => job.owner === owner && job.repo === repo))
+            throw new Error('BUSY');
+        return this.store.cleanup(owner, repo, input);
+    }
+    captureGap(owner, repo, reason) {
+        this.store.authorize(owner, repo);
+        this.recordGap(owner, repo, reason);
+    }
+    /** Trusted observer scope only; works even when the storage connection is down. */
+    recordGap(owner, repo, reason) {
+        for (const key of this.gaps.keys())
+            if (!key.startsWith(`${owner}:`))
+                this.gaps.delete(key);
+        const gap = this.gaps.get(`${owner}:${repo}`) ?? { count: 0, reasons: new Set() };
+        gap.count++;
+        gap.reasons.add(GAP_REASONS.has(reason) ? reason : 'storage_unavailable');
+        this.gaps.set(`${owner}:${repo}`, gap);
+    }
+    status(owner, repo) {
+        this.store.authorize(owner, repo);
+        const manifest = this.store.inspectManifest(owner, repo);
+        const gap = this.gaps.get(`${owner}:${repo}`);
+        const reasons = [...(gap?.reasons ?? [])];
+        if (manifest.unknown_events > 0)
+            reasons.push('unknown_after_restart');
+        const quotaGaps = this.store.quotaGaps(owner);
+        if (quotaGaps > 0)
+            reasons.push('quota');
+        return {
+            schema_version: 1, ok: true, scope: { repository_ref: repo },
+            index: { generation: manifest.generation, indexed_through_event: manifest.indexed_through_event,
+                pending_events: manifest.pending_events, fts_documents: manifest.fts_documents, freshness: manifest.generation === null ? 'missing' : manifest.pending_events ? 'stale' : 'current' },
+            coverage: { complete: reasons.length === 0, reasons },
+            capture_health: { capture_healthy: reasons.length === 0, in_memory_gaps: gap?.count ?? 0, unknown_after_restart: manifest.unknown_events, quota_gaps: quotaGaps },
+            active_jobs: [...this.jobs.values()].filter(job => job.owner === owner && job.repo === repo)
+                .map(({ job_ref, action, started_at }) => ({ job_ref, action, started_at })),
+            storage: { available: true, accounted_bytes: this.store.accountedBytes(), accounting: 'last_explicit_refresh', quota_enforced: true },
+            wiki_enabled: false,
+        };
+    }
+    startJob(owner, repo, action) {
+        this.store.authorize(owner, repo);
+        if (action !== 'sync' && action !== 'rebuild')
+            throw new Error('ACTION_UNSUPPORTED');
+        // Re-pair cannot leave sealed-owner jobs consuming the active owner's limits.
+        for (const [id, job] of this.jobs)
+            if (job.owner !== owner)
+                this.jobs.delete(id);
+        const jobs = [...this.jobs.values()];
+        if (jobs.some(job => job.repo === repo) || jobs.length >= 4)
+            throw new Error('BUSY');
+        const id = randomBytes(24).toString('hex');
+        this.jobs.set(id, { job_ref: id, owner, repo, action, started_at: Date.now() });
+        return id;
+    }
+    /** Foreground work completes before another request can run; cancel only releases a scoped pending job. */
+    cancel(owner, repo, id) {
+        this.finishJob(owner, repo, id);
+        return { job_ref: id, state: 'cancelled' };
+    }
+    finishJob(owner, repo, id) {
+        this.store.authorize(owner, repo);
+        const job = this.jobs.get(id);
+        if (!job || job.owner !== owner || job.repo !== repo)
+            throw new Error('ACCESS_DENIED');
+        this.jobs.delete(id);
+    }
+}

package/dist/context/store.d.ts

@@ -0,0 +1,134 @@
+import { DatabaseSync } from 'node:sqlite';
+/** Only context connection constructor, including read-only handles. */
+export declare function createContextDatabase(path: string, options?: {
+    readOnly?: boolean;
+}): DatabaseSync;
+interface CursorState {
+    generation: number | null;
+    position: number;
+    expires_at: number;
+    query_hash: string;
+}
+/** Device-local storage. State root is supplied by trusted runtime configuration, never tool input. */
+export declare class ContextStore {
+    private readonly stateRoot;
+    readonly registry: DatabaseSync;
+    private readonly root;
+    private readonly key;
+    private readonly cursorKey;
+    private readonly databases;
+    private activeReservation;
+    private activeEpoch;
+    /** Registry provides lease liveness only; repo.sqlite owns epoch authority.
+     * Registry and repository are separate SQLite files, not an atomic transaction. */
+    assertReservationLive(): void;
+    /** Store-owned commit gate: stale caller tokens cannot commit repository work. */
+    commitRepository(db: DatabaseSync, token?: string | undefined): void;
+    constructor(stateRoot: string, options?: {
+        readOnly?: boolean;
+    });
+    private open;
+    activeOwner(): string | null;
+    activateOwner(trustedPairingIdentity: string): string;
+    authorize(owner: string, repo?: string): void;
+    findRepository(owner: string, identity: string): string | null;
+    repository(owner: string, identity: string): string;
+    private repositoryPath;
+    private database;
+    /** Internal modules only; adapters must use authorized domain methods. */
+    repoDatabase(owner: string, repo: string): DatabaseSync;
+    unscopedDatabase(owner: string): DatabaseSync;
+    recordUnscoped(owner: string, reason: 'outside_repo' | 'ambiguous_multi_repo' | 'repo_resolution_failed' | 'quota'): void;
+    append(owner: string, repo: string, input: string | Buffer, options?: {
+        path?: string;
+        maxBytes?: number;
+        checkpoint?: boolean;
+    }): string;
+    /** All persistence callers share the protected installation key; raw secrets are never hashed unkeyed. */
+    redactPayload(input: string | Buffer, options?: {
+        path?: string;
+        maxBytes?: number;
+    }): import("./redact.js").RedactedPayload;
+    read(owner: string, repo: string, ref: string): Record<string, import("node:sqlite").Value>;
+    inspectManifest(owner: string, repo: string): {
+        generation: number | null;
+        indexed_through_event: number;
+        manifest_hash: string | number | bigint | Uint8Array<ArrayBufferLike> | null;
+        pending_events: number;
+        unknown_events: number;
+        fts_documents: number;
+    };
+    /** Query-only access never creates, migrates or opens a writable handle. */
+    withReadDatabase<T>(owner: string, repo: string, action: (db: DatabaseSync) => T): T;
+    signReadCursor(owner: string, repo: string, state: {
+        generation?: unknown;
+        key?: unknown;
+        expires_at?: unknown;
+        [field: string]: unknown;
+    }): string;
+    /** Authenticate bounded metadata only. search/read continuation() enforces expiry,
+     * operation/query identity and generation policy after successful authentication.
+     */
+    parseReadCursor(owner: string, repo: string, token: string): Record<string, unknown>;
+    manifest(owner: string, repo: string): {
+        generation: number | null;
+        indexed_through_event: number;
+        manifest_hash: string | number | bigint | Uint8Array<ArrayBufferLike> | null;
+        pending_events: number;
+        unknown_events: number;
+        fts_documents: number;
+    };
+    private readManifest;
+    beginGeneration(owner: string, repo: string): number;
+    publishGeneration(owner: string, repo: string, generation: number, through: number, manifestHash: string): void;
+    cursor(owner: string, repo: string, query: string, position: number, ttl?: number): string;
+    validateCursor(owner: string, repo: string, token: string, query: string, now?: number): CursorState;
+    /** Explicit maintenance accounting includes DB/WAL/blob files in active and sealed namespaces.
+     * This is not invoked by status and is not quota enforcement (Phase 5).
+     */
+    refreshAccounting(): number;
+    /** Accounted allocation includes sealed namespaces; actual-file scan is explicit, never status IO. */
+    accountedBytes(): number;
+    /** Explicit recovery also works in a continuing process (no restart required).
+     * Admission and foreground sync invoke this sweep; no hidden timer is added.
+     * Registry-first snapshots retain durable living reservations, and reap only
+     * expired leases or demonstrably dead same-host PIDs. Committed evidence is
+     * always tallied from repo DBs, never inferred from reservation allocations.
+     * Logical evidence totals
+     * include sealed stores; physical allocation still gates admission. */
+    reconcileQuota(): number;
+    private reconcileQuotaLocked;
+    /** Trusted local configuration only. Caps can be lowered; no tool exposes this method. */
+    configureQuota(input: Partial<{
+        device_bytes: number;
+        owner_bytes: number;
+        repo_bytes: number;
+        metadata_reserve_bytes: number;
+    }>): void;
+    /** Two-phase, recoverable protocol across separate Registry and Repo SQLite files:
+     * Single-writer invariant: each repository has at most one active writer lease.
+     * Admission checks for a living lease under registry BEGIN IMMEDIATE; the same
+     * mutex serializes reconciliation and is held through repo COMMIT/finalization.
+     * The durable allocation/reacquisition gap cannot admit a second writer lease.
+     * 1. Repo durably increments fencing_state; registry reserves allocation and
+     *    records that epoch as a non-authoritative lease token/cache.
+     * 2. Repo checks exact epoch/id in its writer transaction and commits evidence.
+     * 3. Registry finalizes quota under the same registry-first writer mutex.
+     * This is not distributed atomic commit; reconcileQuota repairs the crash gap.
+     * Includes DB/WAL/SHM and sealed allocations; reserve is never payload space.
+     */
+    quotaWrite<T>(owner: string, repo: string, allocation: number, action: () => T): T;
+    quotaGaps(owner: string): number;
+    private cursorEpoch;
+    /** Destructive domain seam for trusted local owner administration, never MCP dispatch. */
+    cleanup(owner: string, repo: string, input: {
+        before: number;
+        localAdmin: boolean;
+    }): {
+        purged: number;
+        accounted_bytes: number;
+    };
+    databaseFiles(): string[];
+    close(): void;
+}
+export {};