@blokjs/capabilities 2.2.0

package/dist/graph/FakeGraphProvider.js

@@ -0,0 +1,280 @@
+import { GRAPH_MAX_DEPTH, parseGraphFreshnessRequest, parseGraphImpactRequest, parseGraphIndexRequest, parseGraphRelationRequest, parseGraphSearchRequest, parseGraphSymbolRequest, } from "@blokjs/shared";
+import { GraphProviderError } from "./GraphProviderError.js";
+import { checkCancelled, compareScope, indexResponse, makeError, makeFreshness, makeProvenance, makeStatus, response, } from "./GraphProviderSupport.js";
+const DEFAULT_SUPPORTED = ["search", "symbol", "relations", "impact", "freshness", "index"];
+function operationError(operation) {
+    return new GraphProviderError("unsupported", "GRAPH_UNSUPPORTED_OPERATION", `Graph operation '${operation}' is unsupported`, {
+        guidance: "inspect-provider",
+    });
+}
+function invalidRequest(error) {
+    return new GraphProviderError("invalid-query", "GRAPH_INVALID_REQUEST", error instanceof Error ? error.message : "Invalid graph request", { guidance: "narrow-query" });
+}
+function missingError(message) {
+    return new GraphProviderError("not-found", "GRAPH_NOT_FOUND", message, {
+        guidance: "reread-authoritative-source",
+    });
+}
+/** Deterministic in-memory provider used for contract tests and local adapters. */
+export class FakeGraphProvider {
+    id = "fake";
+    version = "fake-1";
+    symbols = new Map();
+    relationsById = new Map();
+    indexedHashes = new Map();
+    supported;
+    now;
+    indexedScope;
+    indexedAt;
+    indexVersion = "fake-index-1";
+    constructor(options = {}) {
+        this.supported = new Set(options.supportedOperations ?? DEFAULT_SUPPORTED);
+        this.now = options.now ?? (() => new Date().toISOString());
+        if (options.files && options.scope) {
+            this.seed(options.scope, options.files);
+        }
+    }
+    seed(scope, files) {
+        const request = { scope, files, reason: "initial" };
+        this.applyIndex(request);
+    }
+    async search(input, options) {
+        checkCancelled(options?.signal);
+        const request = this.parse(() => parseGraphSearchRequest(input));
+        if (!this.supported.has("search"))
+            return this.unsupported("search");
+        const limit = request.limit ?? 50;
+        const freshness = this.scopeMetadata(request.scope);
+        const query = request.query.toLowerCase();
+        const kinds = request.kinds ? new Set(request.kinds) : undefined;
+        const hits = [...this.symbols.values()]
+            .filter((symbol) => !kinds || kinds.has("symbol"))
+            .filter((symbol) => !request.pathPrefix || symbol.location.path.startsWith(request.pathPrefix))
+            .map((symbol) => ({ symbol, score: this.score(symbol, query) }))
+            .filter((match) => match.score > 0)
+            .sort((left, right) => right.score - left.score || left.symbol.id.localeCompare(right.symbol.id))
+            .map(({ symbol, score }) => ({
+            id: symbol.id,
+            kind: "symbol",
+            name: symbol.name,
+            score,
+            symbol,
+            location: symbol.location,
+        }));
+        const truncated = hits.length > limit;
+        const items = hits.slice(0, limit);
+        const states = truncated ? [freshness.state, "truncated"] : [freshness.state];
+        if (items.length === 0)
+            states.push("missing");
+        return response(items, makeStatus(states[0], states.slice(1)), freshness.freshness, freshness.provenance, items.length === 0 ? [makeError(missingError(`No graph symbols matched '${request.query}'`))] : [], truncated ? String(limit) : undefined);
+    }
+    async findSymbol(input, options) {
+        checkCancelled(options?.signal);
+        const request = this.parse(() => parseGraphSymbolRequest(input));
+        if (!this.supported.has("symbol"))
+            return this.unsupported("symbol");
+        const limit = request.limit ?? 50;
+        const freshness = this.scopeMetadata(request.scope, request.path);
+        const items = [...this.symbols.values()]
+            .filter((symbol) => (request.symbolId ? symbol.id === request.symbolId : symbol.name === request.name))
+            .filter((symbol) => !request.path || symbol.location.path === request.path)
+            .sort((left, right) => left.id.localeCompare(right.id))
+            .slice(0, limit);
+        const states = items.length === 0 ? [freshness.state, "missing"] : [freshness.state];
+        return response(items, makeStatus(states[0], states.slice(1)), freshness.freshness, freshness.provenance, items.length === 0 ? [makeError(missingError("Requested symbol is not present in the graph"))] : []);
+    }
+    async relations(input, options) {
+        checkCancelled(options?.signal);
+        const request = this.parse(() => parseGraphRelationRequest(input));
+        if (!this.supported.has("relations"))
+            return this.unsupported("relations");
+        const limit = request.limit ?? 100;
+        const direction = request.direction ?? "outbound";
+        const kinds = request.kinds ? new Set(request.kinds) : undefined;
+        const freshness = this.scopeMetadata(request.scope);
+        const items = [...this.relationsById.values()]
+            .filter((relation) => (direction === "outbound" && relation.from === request.symbolId) ||
+            (direction === "inbound" && relation.to === request.symbolId) ||
+            (direction === "both" && (relation.from === request.symbolId || relation.to === request.symbolId)))
+            .filter((relation) => !kinds || kinds.has(relation.kind))
+            .sort((left, right) => left.id.localeCompare(right.id));
+        const truncated = items.length > limit;
+        const visible = items.slice(0, limit);
+        const states = [freshness.state];
+        if (truncated)
+            states.push("truncated");
+        if (visible.length === 0)
+            states.push("missing");
+        return response(visible, makeStatus(states[0], states.slice(1)), freshness.freshness, freshness.provenance, visible.length === 0 ? [makeError(missingError("No requested graph relations were found"))] : [], truncated ? String(limit) : undefined);
+    }
+    async impact(input, options) {
+        checkCancelled(options?.signal);
+        const request = this.parse(() => parseGraphImpactRequest(input));
+        if (!this.supported.has("impact"))
+            return this.unsupported("impact");
+        const direction = request.direction ?? "outbound";
+        const maxDepth = request.maxDepth ?? GRAPH_MAX_DEPTH;
+        const limit = request.limit ?? 100;
+        const kinds = request.relationKinds ? new Set(request.relationKinds) : undefined;
+        const freshness = this.scopeMetadata(request.scope);
+        const found = new Set();
+        const frontier = [{ id: request.symbolId, depth: 0 }];
+        while (frontier.length > 0) {
+            const current = frontier.shift();
+            if (!current || current.depth >= maxDepth)
+                continue;
+            for (const relation of this.relationsById.values()) {
+                if (kinds && !kinds.has(relation.kind))
+                    continue;
+                const next = direction === "outbound"
+                    ? relation.from === current.id
+                        ? relation.to
+                        : undefined
+                    : relation.to === current.id
+                        ? relation.from
+                        : undefined;
+                if (!next || found.has(next))
+                    continue;
+                found.add(next);
+                frontier.push({ id: next, depth: current.depth + 1 });
+            }
+        }
+        const items = [...found]
+            .map((id) => this.symbols.get(id))
+            .filter((symbol) => symbol !== undefined)
+            .sort((left, right) => left.id.localeCompare(right.id));
+        const truncated = items.length > limit;
+        const visible = items.slice(0, limit);
+        const states = [freshness.state];
+        if (truncated)
+            states.push("truncated");
+        if (visible.length === 0)
+            states.push("missing");
+        return response(visible, makeStatus(states[0], states.slice(1)), freshness.freshness, freshness.provenance, visible.length === 0 ? [makeError(missingError("No impacted symbols were found"))] : [], truncated ? String(limit) : undefined);
+    }
+    async freshness(input, options) {
+        checkCancelled(options?.signal);
+        const request = this.parse(() => parseGraphFreshnessRequest(input));
+        if (!this.supported.has("freshness"))
+            return this.unsupported("freshness");
+        const paths = request.paths ?? [...this.indexedHashes.keys()].sort();
+        const metadata = this.scopeMetadata(request.scope);
+        const items = paths
+            .filter((candidate) => this.indexedHashes.has(candidate))
+            .map((candidate) => ({ path: candidate, contentHash: this.indexedHashes.get(candidate) }));
+        const missingPaths = paths.filter((candidate) => !this.indexedHashes.has(candidate));
+        const states = [metadata.state];
+        if (missingPaths.length > 0)
+            states.push("missing");
+        return response(items, makeStatus(states[0], states.slice(1)), metadata.freshness, metadata.provenance, missingPaths.map((path) => makeError(missingError("Path is not present in the graph"), path)));
+    }
+    async index(input, options) {
+        checkCancelled(options?.signal);
+        if (!this.supported.has("index")) {
+            const error = operationError("index");
+            return indexResponse([], [], makeStatus("unsupported"), makeFreshness("unknown", this.now(), undefined, { reason: error.message }), undefined, [makeError(error)]);
+        }
+        let request;
+        try {
+            request = parseGraphIndexRequest(input);
+        }
+        catch (error) {
+            throw invalidRequest(error);
+        }
+        checkCancelled(options?.signal);
+        this.applyIndex(request);
+        const provenance = this.indexedScope
+            ? makeProvenance(this.id, this.version, this.indexVersion, this.indexedScope, this.indexedAt ?? this.now())
+            : undefined;
+        return indexResponse(request.files.map((file) => file.path).sort(), [], makeStatus("fresh"), makeFreshness("fresh", this.now(), this.indexedAt), provenance);
+    }
+    applyIndex(request) {
+        for (const file of request.files) {
+            for (const [id, symbol] of this.symbols)
+                if (symbol.location.path === file.path)
+                    this.symbols.delete(id);
+            for (const [id, relation] of this.relationsById)
+                if (relation.location?.path === file.path)
+                    this.relationsById.delete(id);
+            for (const symbol of file.symbols)
+                this.symbols.set(symbol.id, symbol);
+            for (const relation of file.relations)
+                this.relationsById.set(relation.id, relation);
+            this.indexedHashes.set(file.path, file.contentHash);
+        }
+        this.indexedScope = {
+            repository: request.scope.repository,
+            worktree: request.scope.worktree,
+            commit: request.scope.commit ?? request.scope.worktree?.commit,
+        };
+        this.indexVersion = request.indexVersion ?? this.indexVersion;
+        this.indexedAt = this.now();
+    }
+    score(symbol, query) {
+        const name = symbol.name.toLowerCase();
+        const id = symbol.id.toLowerCase();
+        if (name === query || id === query)
+            return 1;
+        if (name.startsWith(query) || id.startsWith(query))
+            return 0.9;
+        if (name.includes(query) || id.includes(query) || symbol.location.path.toLowerCase().includes(query))
+            return 0.75;
+        return symbol.signature?.toLowerCase().includes(query) ? 0.6 : 0;
+    }
+    parse(parser) {
+        try {
+            return parser();
+        }
+        catch (error) {
+            throw invalidRequest(error);
+        }
+    }
+    unsupported(operation) {
+        const error = operationError(operation);
+        return response([], makeStatus("unsupported"), makeFreshness("unknown", this.now(), undefined, { reason: error.message }), undefined, [makeError(error)]);
+    }
+    scopeMetadata(scope, path) {
+        const checkedAt = this.now();
+        if (!this.indexedScope || !this.indexedAt) {
+            return {
+                state: "missing",
+                freshness: makeFreshness("unknown", checkedAt, undefined, { reason: "index is unavailable" }),
+            };
+        }
+        const comparison = compareScope(this.indexedScope, scope);
+        let state = comparison.state === "unknown" ? "missing" : comparison.state;
+        let reason = comparison.reason;
+        let observedContentHash;
+        let indexedContentHash;
+        const paths = path ? [path] : Object.keys(scope.contentHashes ?? {});
+        for (const candidate of paths) {
+            const observed = scope.contentHashes?.[candidate];
+            const indexed = this.indexedHashes.get(candidate);
+            if (observed && indexed && observed !== indexed) {
+                state = "conflict";
+                reason = "authoritative content hash differs from the index";
+                observedContentHash = observed;
+                indexedContentHash = indexed;
+                break;
+            }
+            if (observed && !indexed) {
+                state = "missing";
+                reason = "path is not indexed";
+                observedContentHash = observed;
+                break;
+            }
+        }
+        const freshnessState = state === "fresh" ? "fresh" : "stale";
+        return {
+            state,
+            freshness: makeFreshness(freshnessState, checkedAt, this.indexedAt, {
+                indexedCommit: comparison.indexedCommit,
+                observedCommit: comparison.observedCommit,
+                indexedContentHash,
+                observedContentHash,
+                reason,
+            }),
+            provenance: makeProvenance(this.id, this.version, this.indexVersion, this.indexedScope, this.indexedAt),
+        };
+    }
+}

package/dist/graph/GraphCapabilityManifests.d.ts

@@ -0,0 +1,5 @@
+import type { CapabilityManifestV1 } from "@blokjs/shared";
+/** Existing H0-02 vocabulary for graph queries; authorization stays with PolicyProvider. */
+export declare const GRAPH_QUERY_CAPABILITY_MANIFEST: CapabilityManifestV1;
+/** Index persistence is a derived-index write, never a workspace/source write. */
+export declare const GRAPH_INDEX_CAPABILITY_MANIFEST: CapabilityManifestV1;

package/dist/graph/GraphCapabilityManifests.js

@@ -0,0 +1,22 @@
+/** Existing H0-02 vocabulary for graph queries; authorization stays with PolicyProvider. */
+export const GRAPH_QUERY_CAPABILITY_MANIFEST = Object.freeze({
+    version: "1",
+    classification: "agent-compatible",
+    effects: ["read"],
+    capabilities: ["graph.query"],
+    secrets: [],
+    determinism: "external",
+    idempotency: "idempotent",
+    maturity: "experimental",
+});
+/** Index persistence is a derived-index write, never a workspace/source write. */
+export const GRAPH_INDEX_CAPABILITY_MANIFEST = Object.freeze({
+    version: "1",
+    classification: "agent-compatible",
+    effects: ["read", "write"],
+    capabilities: ["graph.index"],
+    secrets: [],
+    determinism: "external",
+    idempotency: "conditionally-idempotent",
+    maturity: "experimental",
+});

package/dist/graph/GraphProviderError.d.ts

@@ -0,0 +1,12 @@
+import type { GraphErrorCategory } from "@blokjs/shared";
+export declare class GraphProviderError extends Error {
+    readonly code: string;
+    readonly category: GraphErrorCategory;
+    readonly retryable: boolean;
+    readonly guidance: "reread-authoritative-source" | "retry" | "narrow-query" | "inspect-provider" | "none";
+    constructor(category: GraphErrorCategory, code: string, message: string, options?: {
+        retryable?: boolean;
+        guidance?: "reread-authoritative-source" | "retry" | "narrow-query" | "inspect-provider" | "none";
+    });
+    static cancelled(): GraphProviderError;
+}

package/dist/graph/GraphProviderError.js

@@ -0,0 +1,20 @@
+export class GraphProviderError extends Error {
+    code;
+    category;
+    retryable;
+    guidance;
+    constructor(category, code, message, options = {}) {
+        super(message);
+        this.name = "GraphProviderError";
+        this.category = category;
+        this.code = code;
+        this.retryable = options.retryable ?? false;
+        this.guidance = options.guidance ?? "none";
+    }
+    static cancelled() {
+        return new GraphProviderError("cancelled", "GRAPH_CANCELLED", "Graph operation was cancelled", {
+            retryable: true,
+            guidance: "retry",
+        });
+    }
+}

package/dist/graph/GraphProviderSupport.d.ts

@@ -0,0 +1,20 @@
+import { type GraphError, type GraphFreshness, type GraphIndexResponse, type GraphProvenance, type GraphQueryResponse, type GraphRepositoryIdentity, type GraphResultState, type GraphResultStatus, type GraphScope, type GraphWorktreeIdentity } from "@blokjs/shared";
+import { GraphProviderError } from "./GraphProviderError.js";
+export interface IndexedScope {
+    readonly repository: GraphRepositoryIdentity;
+    readonly worktree?: GraphWorktreeIdentity;
+    readonly commit?: string;
+}
+export declare function checkCancelled(signal?: AbortSignal): void;
+export declare function makeStatus(primary: GraphResultState, additional?: readonly GraphResultState[]): GraphResultStatus;
+export declare function makeError(error: GraphProviderError, path?: string): GraphError;
+export declare function makeProvenance(provider: string, providerVersion: string, indexVersion: string, scope: IndexedScope, indexedAt: string): GraphProvenance;
+export declare function makeFreshness(state: GraphFreshness["state"], checkedAt: string, indexedAt?: string, comparison?: Partial<Pick<GraphFreshness, "indexedCommit" | "observedCommit" | "indexedContentHash" | "observedContentHash" | "reason">>): GraphFreshness;
+export declare function response<T>(items: readonly T[], status: GraphResultStatus, freshness: GraphFreshness, provenance: GraphProvenance | undefined, errors?: readonly GraphError[], nextCursor?: string): GraphQueryResponse<T>;
+export declare function indexResponse(indexedFiles: readonly string[], skippedFiles: readonly string[], status: GraphResultStatus, freshness: GraphFreshness, provenance: GraphProvenance | undefined, errors?: readonly GraphError[]): GraphIndexResponse;
+export declare function compareScope(indexed: IndexedScope | undefined, requested: GraphScope): {
+    state: "fresh" | "stale" | "conflict" | "unknown";
+    reason?: string;
+    indexedCommit?: string;
+    observedCommit?: string;
+};

package/dist/graph/GraphProviderSupport.js

@@ -0,0 +1,95 @@
+import { GRAPH_CONTRACT_VERSION, } from "@blokjs/shared";
+import { GraphProviderError } from "./GraphProviderError.js";
+export function checkCancelled(signal) {
+    if (signal?.aborted)
+        throw GraphProviderError.cancelled();
+}
+export function makeStatus(primary, additional = []) {
+    const states = [...new Set([primary, ...additional])];
+    return { primary, states, complete: states.every((state) => state === "fresh") };
+}
+export function makeError(error, path) {
+    return {
+        code: error.code,
+        category: error.category,
+        message: error.message,
+        retryable: error.retryable,
+        guidance: error.guidance,
+        ...(path ? { path } : {}),
+    };
+}
+export function makeProvenance(provider, providerVersion, indexVersion, scope, indexedAt) {
+    return {
+        source: "derived-index",
+        provider,
+        providerVersion,
+        indexVersion,
+        repository: scope.repository,
+        ...(scope.worktree ? { worktree: scope.worktree } : {}),
+        ...(scope.commit ? { commit: scope.commit } : {}),
+        indexedAt,
+    };
+}
+export function makeFreshness(state, checkedAt, indexedAt, comparison = {}) {
+    return {
+        state,
+        checkedAt,
+        ...(indexedAt ? { indexedAt } : {}),
+        ...comparison,
+    };
+}
+export function response(items, status, freshness, provenance, errors = [], nextCursor) {
+    return {
+        version: GRAPH_CONTRACT_VERSION,
+        authority: "navigation-only",
+        items,
+        status,
+        freshness,
+        ...(provenance ? { provenance } : {}),
+        errors,
+        ...(nextCursor ? { nextCursor } : {}),
+    };
+}
+export function indexResponse(indexedFiles, skippedFiles, status, freshness, provenance, errors = []) {
+    return {
+        version: GRAPH_CONTRACT_VERSION,
+        authority: "navigation-only",
+        indexedFiles,
+        skippedFiles,
+        status,
+        freshness,
+        ...(provenance ? { provenance } : {}),
+        errors,
+    };
+}
+function sameIdentity(left, right) {
+    return left.provider === right.provider && left.id === right.id && left.revision === right.revision;
+}
+function sameWorktree(left, right) {
+    if (!left || !right)
+        return left === right;
+    return left.id === right.id && left.branch === right.branch;
+}
+export function compareScope(indexed, requested) {
+    if (!indexed)
+        return { state: "unknown", reason: "index is unavailable" };
+    if (!sameIdentity(indexed.repository, requested.repository)) {
+        return { state: "stale", reason: "repository identity differs" };
+    }
+    if (!sameWorktree(indexed.worktree, requested.worktree)) {
+        return { state: "stale", reason: "worktree identity differs" };
+    }
+    const requestedCommit = requested.commit ?? requested.worktree?.commit;
+    if (indexed.commit !== requestedCommit) {
+        return {
+            state: "stale",
+            reason: "indexed commit differs",
+            indexedCommit: indexed.commit,
+            observedCommit: requestedCommit,
+        };
+    }
+    if (requested.worktree?.overlay === "uncommitted" || requested.worktree?.dirty === true) {
+        return { state: "stale", reason: "working tree has an uncommitted overlay" };
+    }
+    return { state: "fresh" };
+}

package/dist/graph/TetrixGraphProvider.d.ts

@@ -0,0 +1,35 @@
+import { type GraphFreshnessRequest, type GraphImpactRequest, type GraphIndexRequest, type GraphIndexResponse, type GraphLocation, type GraphProvider, type GraphQueryOptions, type GraphQueryResponse, type GraphRelation, type GraphRelationRequest, type GraphSearchHit, type GraphSearchRequest, type GraphSymbol, type GraphSymbolRequest } from "@blokjs/shared";
+/**
+ * Transport seam for Tetrix. The repository does not vendor a Tetrix client;
+ * an integration supplies this narrow transport without exposing its native
+ * response shapes to workflows.
+ */
+export interface TetrixTransport {
+    search(request: GraphSearchRequest, options?: GraphQueryOptions): Promise<unknown>;
+    findSymbol(request: GraphSymbolRequest, options?: GraphQueryOptions): Promise<unknown>;
+    relations(request: GraphRelationRequest, options?: GraphQueryOptions): Promise<unknown>;
+    impact(request: GraphImpactRequest, options?: GraphQueryOptions): Promise<unknown>;
+    freshness(request: GraphFreshnessRequest, options?: GraphQueryOptions): Promise<unknown>;
+    index(request: GraphIndexRequest, options?: GraphQueryOptions): Promise<unknown>;
+}
+export interface TetrixGraphProviderOptions {
+    readonly providerVersion?: string;
+    readonly indexVersion?: string;
+}
+/** First-party seam for Tetrix; only normalized Blok graph contracts escape it. */
+export declare class TetrixGraphProvider implements GraphProvider {
+    private readonly transport;
+    readonly id = "tetrix";
+    readonly version: string;
+    private readonly indexVersion;
+    constructor(transport: TetrixTransport, options?: TetrixGraphProviderOptions);
+    search(request: GraphSearchRequest, options?: GraphQueryOptions): Promise<GraphQueryResponse<GraphSearchHit>>;
+    findSymbol(request: GraphSymbolRequest, options?: GraphQueryOptions): Promise<GraphQueryResponse<GraphSymbol>>;
+    relations(request: GraphRelationRequest, options?: GraphQueryOptions): Promise<GraphQueryResponse<GraphRelation>>;
+    impact(request: GraphImpactRequest, options?: GraphQueryOptions): Promise<GraphQueryResponse<GraphSymbol>>;
+    freshness(request: GraphFreshnessRequest, options?: GraphQueryOptions): Promise<GraphQueryResponse<GraphLocation>>;
+    index(request: GraphIndexRequest, options?: GraphQueryOptions): Promise<GraphIndexResponse>;
+    private stampQuery;
+    private stampIndex;
+    private provenance;
+}

package/dist/graph/TetrixGraphProvider.js

@@ -0,0 +1,99 @@
+import { GraphContractError, GraphLocationSchema, GraphRelationSchema, GraphSearchHitSchema, GraphSymbolSchema, parseGraphFreshnessRequest, parseGraphImpactRequest, parseGraphIndexRequest, parseGraphIndexResponse, parseGraphQueryResponse, parseGraphRelationRequest, parseGraphSearchRequest, parseGraphSymbolRequest, } from "@blokjs/shared";
+import { GraphProviderError } from "./GraphProviderError.js";
+function invalidResponse(error) {
+    return new GraphProviderError("internal", "GRAPH_INVALID_PROVIDER_RESPONSE", error instanceof Error ? error.message : "Tetrix returned an invalid graph response", { guidance: "inspect-provider" });
+}
+function call(operation, parse) {
+    return operation()
+        .then((value) => {
+        try {
+            return parse(value);
+        }
+        catch (error) {
+            if (error instanceof GraphProviderError)
+                throw error;
+            if (error instanceof GraphContractError)
+                throw invalidResponse(error);
+            throw invalidResponse(error);
+        }
+    })
+        .catch((error) => {
+        if (error instanceof GraphProviderError)
+            throw error;
+        throw new GraphProviderError("provider-unavailable", "GRAPH_TETRIX_UNAVAILABLE", String(error), {
+            retryable: true,
+            guidance: "retry",
+        });
+    });
+}
+function validateRequest(parser, signal) {
+    if (signal?.aborted)
+        throw GraphProviderError.cancelled();
+    try {
+        return parser();
+    }
+    catch (error) {
+        throw new GraphProviderError("invalid-query", "GRAPH_INVALID_REQUEST", error instanceof Error ? error.message : "Invalid graph request", { guidance: "narrow-query" });
+    }
+}
+/** First-party seam for Tetrix; only normalized Blok graph contracts escape it. */
+export class TetrixGraphProvider {
+    transport;
+    id = "tetrix";
+    version;
+    indexVersion;
+    constructor(transport, options = {}) {
+        this.transport = transport;
+        this.version = options.providerVersion ?? "tetrix-1";
+        this.indexVersion = options.indexVersion ?? "tetrix-index-unknown";
+    }
+    search(request, options) {
+        const normalized = validateRequest(() => parseGraphSearchRequest(request), options?.signal);
+        return call(() => this.transport.search(normalized, options), (value) => this.stampQuery(parseGraphQueryResponse(GraphSearchHitSchema, value), normalized));
+    }
+    findSymbol(request, options) {
+        const normalized = validateRequest(() => parseGraphSymbolRequest(request), options?.signal);
+        return call(() => this.transport.findSymbol(normalized, options), (value) => this.stampQuery(parseGraphQueryResponse(GraphSymbolSchema, value), normalized));
+    }
+    relations(request, options) {
+        const normalized = validateRequest(() => parseGraphRelationRequest(request), options?.signal);
+        return call(() => this.transport.relations(normalized, options), (value) => this.stampQuery(parseGraphQueryResponse(GraphRelationSchema, value), normalized));
+    }
+    impact(request, options) {
+        const normalized = validateRequest(() => parseGraphImpactRequest(request), options?.signal);
+        return call(() => this.transport.impact(normalized, options), (value) => this.stampQuery(parseGraphQueryResponse(GraphSymbolSchema, value), normalized));
+    }
+    freshness(request, options) {
+        const normalized = validateRequest(() => parseGraphFreshnessRequest(request), options?.signal);
+        return call(() => this.transport.freshness(normalized, options), (value) => this.stampQuery(parseGraphQueryResponse(GraphLocationSchema, value), normalized));
+    }
+    index(request, options) {
+        const normalized = validateRequest(() => parseGraphIndexRequest(request), options?.signal);
+        return call(() => this.transport.index(normalized, options), (value) => this.stampIndex(parseGraphIndexResponse(value), normalized));
+    }
+    stampQuery(result, request) {
+        return {
+            ...result,
+            provenance: this.provenance(result.provenance, request.scope, result.freshness.indexedAt),
+        };
+    }
+    stampIndex(result, request) {
+        return {
+            ...result,
+            provenance: this.provenance(result.provenance, request.scope, result.freshness.indexedAt, request.indexVersion),
+        };
+    }
+    provenance(existing, scope, indexedAt, indexVersion = this.indexVersion) {
+        return {
+            ...(existing ?? {}),
+            source: "derived-index",
+            provider: this.id,
+            providerVersion: this.version,
+            indexVersion,
+            repository: existing?.repository ?? scope.repository,
+            ...(existing?.worktree || scope.worktree ? { worktree: existing?.worktree ?? scope.worktree } : {}),
+            ...(existing?.commit || scope.commit ? { commit: existing?.commit ?? scope.commit } : {}),
+            ...(existing?.indexedAt || indexedAt ? { indexedAt: existing?.indexedAt ?? indexedAt } : {}),
+        };
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,11 @@
+export { WORKSPACE_FILESYSTEM_CONTRACT_VERSION, WORKSPACE_FILESYSTEM_OPERATIONS, WORKSPACE_FILESYSTEM_MAX_PATH_LENGTH, WORKSPACE_FILESYSTEM_MAX_QUERY_LENGTH, WORKSPACE_FILESYSTEM_MAX_READ_BYTES, WORKSPACE_FILESYSTEM_MAX_WRITE_BYTES, WORKSPACE_FILESYSTEM_MAX_LIST_FILES, WORKSPACE_FILESYSTEM_MAX_SEARCH_FILES, WORKSPACE_FILESYSTEM_MAX_SEARCH_MATCHES, WORKSPACE_FILESYSTEM_MAX_SEARCH_BYTES, WORKSPACE_FILESYSTEM_MAX_LINES, WORKSPACE_FILESYSTEM_MAX_WATCH_EVENTS, WORKSPACE_FILESYSTEM_MAX_DURATION_MS, WORKSPACE_FILESYSTEM_MAX_WATCH_DEBOUNCE_MS, type WorkspaceFilesystemOperation, type WorkspaceRootInput, type WorkspaceRoot, type WorkspaceFilesystemLimits, type WorkspaceFilesystemPolicyRequest, type WorkspaceFilesystemPolicy, type WorkspaceFilesystemOptions, type WorkspacePathInput, type WorkspaceFileKind, type WorkspaceArtifact, type WorkspaceFileMetadata, type WorkspaceMetadataInput, type WorkspaceListInput, type WorkspaceListResult, type WorkspaceReadEncoding, type WorkspaceReadInput, type WorkspaceReadResult, type WorkspaceSearchInput, type WorkspaceSearchMatch, type WorkspaceSearchResult, type WorkspaceWriteInput, type WorkspaceWriteResult, type WorkspaceTextPatch, type WorkspacePatchInput, type WorkspaceWatchInput, type WorkspaceWatchEvent, type WorkspacePolicyDecision, } from "./contracts.js";
+export { WORKSPACE_FILESYSTEM_ERROR_CODES, WorkspaceFilesystemError, type WorkspaceFilesystemErrorCode, } from "./errors.js";
+export { WorkspaceFilesystemCapability, workspaceFilesystemManifest, workspaceFilesystemAuthority, workspaceRelativePath, } from "./WorkspaceFilesystemCapability.js";
+export { BoundedGraphIndexer } from "./graph/BoundedGraphIndexer.js";
+export type { BoundedGraphIndexerOptions, GraphIndexJobHandle, GraphIndexerEvent, GraphIndexerEnqueueOptions, } from "./graph/BoundedGraphIndexer.js";
+export { FakeGraphProvider } from "./graph/FakeGraphProvider.js";
+export type { FakeGraphProviderOptions } from "./graph/FakeGraphProvider.js";
+export { GRAPH_INDEX_CAPABILITY_MANIFEST, GRAPH_QUERY_CAPABILITY_MANIFEST } from "./graph/GraphCapabilityManifests.js";
+export { GraphProviderError } from "./graph/GraphProviderError.js";
+export { TetrixGraphProvider } from "./graph/TetrixGraphProvider.js";
+export type { TetrixGraphProviderOptions, TetrixTransport } from "./graph/TetrixGraphProvider.js";

package/dist/index.js

@@ -0,0 +1,8 @@
+export { WORKSPACE_FILESYSTEM_CONTRACT_VERSION, WORKSPACE_FILESYSTEM_OPERATIONS, WORKSPACE_FILESYSTEM_MAX_PATH_LENGTH, WORKSPACE_FILESYSTEM_MAX_QUERY_LENGTH, WORKSPACE_FILESYSTEM_MAX_READ_BYTES, WORKSPACE_FILESYSTEM_MAX_WRITE_BYTES, WORKSPACE_FILESYSTEM_MAX_LIST_FILES, WORKSPACE_FILESYSTEM_MAX_SEARCH_FILES, WORKSPACE_FILESYSTEM_MAX_SEARCH_MATCHES, WORKSPACE_FILESYSTEM_MAX_SEARCH_BYTES, WORKSPACE_FILESYSTEM_MAX_LINES, WORKSPACE_FILESYSTEM_MAX_WATCH_EVENTS, WORKSPACE_FILESYSTEM_MAX_DURATION_MS, WORKSPACE_FILESYSTEM_MAX_WATCH_DEBOUNCE_MS, } from "./contracts.js";
+export { WORKSPACE_FILESYSTEM_ERROR_CODES, WorkspaceFilesystemError, } from "./errors.js";
+export { WorkspaceFilesystemCapability, workspaceFilesystemManifest, workspaceFilesystemAuthority, workspaceRelativePath, } from "./WorkspaceFilesystemCapability.js";
+export { BoundedGraphIndexer } from "./graph/BoundedGraphIndexer.js";
+export { FakeGraphProvider } from "./graph/FakeGraphProvider.js";
+export { GRAPH_INDEX_CAPABILITY_MANIFEST, GRAPH_QUERY_CAPABILITY_MANIFEST } from "./graph/GraphCapabilityManifests.js";
+export { GraphProviderError } from "./graph/GraphProviderError.js";
+export { TetrixGraphProvider } from "./graph/TetrixGraphProvider.js";

package/package.json

@@ -0,0 +1,31 @@
+{
+	"name": "@blokjs/capabilities",
+	"version": "2.2.0",
+	"description": "Trusted, bounded capability adapters for Blok harnesses.",
+	"type": "module",
+	"main": "dist/index.js",
+	"types": "dist/index.d.ts",
+	"files": ["dist"],
+	"scripts": {
+		"build": "rm -rf dist && bun run tsc",
+		"build:dev": "tsc --watch",
+		"test": "vitest run",
+		"test:dev": "vitest",
+		"typecheck": "tsc --noEmit"
+	},
+	"keywords": ["blok", "capabilities", "filesystem", "harness"],
+	"license": "MIT",
+	"dependencies": {
+		"@blokjs/shared": "^2.1.0",
+		"uuid": "^11.1.0"
+	},
+	"devDependencies": {
+		"@types/node": "^22.15.21",
+		"typescript": "^5.8.3",
+		"vitest": "^4.0.18"
+	},
+	"private": false,
+	"publishConfig": {
+		"access": "public"
+	}
+}