pilotswarm-sdk 0.2.0 → 0.2.2

package/dist/graph-store.d.ts

@@ -0,0 +1,243 @@
+/**
+ * Graph Store — the OPTIONAL open knowledge graph contract (enhancedfactstore
+ * 07 D2).
+ *
+ * The graph is a SEPARATE, independently injected interface — NOT part of
+ * `EnhancedFactStore` and NOT a capability on the fact store. The SDK owns this
+ * contract; a concrete provider (e.g. pilotswarm-horizon-store's
+ * `HorizonDBGraphStore`, AGE-backed) implements it. The runtime registers graph
+ * tools iff a `graphStore` was injected (`!!graphStore`) — there is no
+ * fact-store sniff.
+ *
+ * The graph stores ids + structure only (never fact values or ACLs). Evidence
+ * scope_keys are opaque pointers; resolving them back to fact values is the
+ * caller's tool-layer composition:
+ *   graphStore.searchGraphNodes(...) -> scopeKeys -> factStore.readFacts({ scopeKeys })
+ *
+ * @module
+ */
+import type { AccessContext } from "./facts-store.js";
+/**
+ * Reserved namespace token for the unscoped graph partition. Graph records with
+ * no namespace property (NULL) are the `default` partition: writes of `default`
+ * (or empty) store no namespace, and reads of `default` match `namespace IS
+ * NULL`. `default` is always present in the registry and cannot be archived or
+ * deleted (graph-fact-search enhancements).
+ */
+export declare const DEFAULT_GRAPH_NAMESPACE = "default";
+export interface GraphNodeInput {
+    kind: string;
+    name: string;
+    /** Optional corpus/domain namespace. Prefix semantics match facts_search:
+     * "corpus/acme" includes "corpus/acme" and "corpus/acme/...". */
+    namespace?: string;
+    aliases?: string[];
+    evidence?: string[];
+    agentId: string;
+}
+export interface GraphEdgeInput {
+    fromKey: string;
+    toKey: string;
+    predicate: string;
+    /** Optional corpus/domain namespace for this assertion/edge. */
+    namespace?: string;
+    confidence?: number;
+    evidence?: string[];
+    agentId: string;
+    model?: string;
+}
+export interface GraphNodeQuery {
+    kind?: string;
+    nameLike?: string;
+    /** Optional corpus/domain namespace filter. Matches exact namespace OR any
+     * descendant (`namespace` + "/..."). */
+    namespace?: string;
+    /** Fact scopeKeys OR node keys anchoring the query. Fact seeds pivot via
+     * EVIDENCED_BY (inaccessible fact seeds are IGNORED — treated unknown);
+     * node seeds expand directly. */
+    seeds?: string[];
+    depth?: number;
+    minConfidence?: number;
+    limit?: number;
+}
+export interface GraphEdgeQuery {
+    predicate?: string;
+    predicateKey?: string;
+    fromKey?: string;
+    toKey?: string;
+    /** Optional corpus/domain namespace filter. An edge matches when the edge
+     * itself OR either endpoint is in the namespace subtree. */
+    namespace?: string;
+    minConfidence?: number;
+    limit?: number;
+}
+export interface GraphNamespaceQuery {
+    namespace?: string;
+}
+export interface GraphNodeRef {
+    nodeKey: string;
+    kind: string;
+    name: string;
+    namespace?: string;
+    aliases: string[];
+    created: boolean;
+}
+export interface GraphNodeHit {
+    nodeKey: string;
+    kind: string;
+    name: string;
+    namespace?: string;
+    aliases: string[];
+    /** EVIDENCED_BY fact scopeKeys, FILTERED to caller-accessible keys. */
+    evidence: string[];
+    score?: number;
+}
+export interface GraphEdgeRef {
+    fromKey: string;
+    toKey: string;
+    predicate: string;
+    predicateKey: string;
+    namespace?: string;
+    confidence: number;
+    observations: number;
+    reinforced: boolean;
+}
+export interface GraphEvidenceRemovalResult {
+    scopeKey: string;
+    nodeEvidenceRemoved: number;
+    edgeEvidenceRemoved: number;
+    nodesDeleted: number;
+    edgesDeleted: number;
+}
+export interface GraphEdgeHit {
+    fromKey: string;
+    toKey: string;
+    predicate: string;
+    predicateKey: string;
+    namespace?: string;
+    confidence: number;
+    observations: number;
+    /** ACL-filtered, as on GraphNodeHit. */
+    evidence: string[];
+}
+export interface SubGraph {
+    nodes: {
+        nodeKey: string;
+        kind: string;
+        name: string;
+        namespace?: string;
+    }[];
+    edges: {
+        fromKey: string;
+        toKey: string;
+        predicate: string;
+        namespace?: string;
+        confidence: number;
+    }[];
+}
+/**
+ * Minimal, skill-file-style discovery frontmatter for a graph namespace. Kept
+ * deliberately small: a short name and a `description` that lets an LLM decide
+ * whether the corpus is relevant before loading details or searching the graph.
+ */
+export interface GraphNamespaceFrontmatter {
+    /** Short label. Defaults to the namespace when omitted. */
+    name?: string;
+    /** When to use this corpus — the discovery hint a reader agent reads. */
+    description: string;
+}
+/** A registered graph namespace (corpus) descriptor. */
+export interface GraphNamespaceInfo {
+    namespace: string;
+    archived: boolean;
+    frontmatter: GraphNamespaceFrontmatter;
+    source?: string;
+    nodeSchema?: unknown;
+    edgeSchema?: unknown;
+    harvestConfig?: unknown;
+    createdAt?: string;
+    updatedAt?: string;
+}
+/** Upsert input for a namespace registry row (graph-owned, relational). */
+export interface GraphNamespaceInput {
+    namespace: string;
+    frontmatter: GraphNamespaceFrontmatter;
+    source?: string;
+    nodeSchema?: unknown;
+    edgeSchema?: unknown;
+    harvestConfig?: unknown;
+    /** Upsert may clear `archived` back to false; defaults to false on create. */
+    archived?: boolean;
+}
+export interface GraphNamespaceListQuery {
+    /** String-prefix filter over registry namespace keys (not an AGE subtree). */
+    prefix?: string;
+    /** Include archived rows. Default false. */
+    includeArchived?: boolean;
+    /** Include detail fields (source/schemas/harvestConfig). Default false. */
+    includeDetails?: boolean;
+}
+/** Result of a destructive namespace delete. */
+export interface GraphNamespaceDeleteResult {
+    deleted: boolean;
+    nodesDeleted: number;
+    edgesDeleted: number;
+}
+export interface GraphStore {
+    initialize(): Promise<void>;
+    close(): Promise<void>;
+    searchGraphNodes(q: GraphNodeQuery, access?: AccessContext): Promise<GraphNodeHit[]>;
+    searchGraphEdges(q: GraphEdgeQuery, access?: AccessContext): Promise<GraphEdgeHit[]>;
+    graphNeighbourhood(nodeKey: string, depth: number, access?: AccessContext, opts?: GraphNamespaceQuery): Promise<SubGraph>;
+    /** Optional provider-owned predicate normalizer for metrics/tooling. */
+    normalizePredicateKey?(predicate: string): string;
+    upsertGraphNode(n: GraphNodeInput): Promise<GraphNodeRef>;
+    upsertGraphEdge(e: GraphEdgeInput): Promise<GraphEdgeRef>;
+    mergeGraphNodes(fromKey: string, intoKey: string, reason: string, opts?: GraphNamespaceQuery): Promise<void>;
+    deleteGraphNode(nodeKey: string, opts?: GraphNamespaceQuery): Promise<boolean>;
+    deleteGraphEdge(fromKey: string, toKey: string, predicateKey: string, opts?: GraphNamespaceQuery): Promise<boolean>;
+    /** Remove a deleted fact's scopeKey from graph evidence, deleting graph
+     * edges and nodes that become evidence-less as a result. */
+    removeGraphEvidence(scopeKey: string, opts?: GraphNamespaceQuery): Promise<GraphEvidenceRemovalResult>;
+    /**
+     * OPTIONAL cheap aggregate for `graph_stats` (enhancedfactstore 07 P4):
+     * total node + edge counts via a single store-side query (e.g. an AGE
+     * `MATCH (n) RETURN count(n)` / `MATCH ()-[r]->() RETURN count(r)`), NOT a
+     * client-side fan-out traversal. When a provider does not implement this,
+     * the graph_stats tool falls back to a bounded node sample and omits the
+     * exact edge count. `uncrawledFacts` is optional here — the tool reads the
+     * crawl backlog from the base FactStore when the provider omits it.
+     */
+    graphStats?(opts?: GraphNamespaceQuery): Promise<{
+        nodeCount: number;
+        edgeCount: number;
+        uncrawledFacts?: number;
+    }>;
+    /** List registered namespaces. Compact by default (namespace, archived,
+     * frontmatter); detail fields only with `includeDetails`. Excludes archived
+     * rows unless `includeArchived`. No pagination — the set is small. */
+    listGraphNamespaces?(q?: GraphNamespaceListQuery): Promise<GraphNamespaceInfo[]>;
+    /** Full descriptor for one namespace (regardless of archived), or null. */
+    getGraphNamespace?(namespace: string): Promise<GraphNamespaceInfo | null>;
+    /** Upsert a namespace registry row (ON CONFLICT (namespace) DO UPDATE). */
+    upsertGraphNamespace?(input: GraphNamespaceInput): Promise<GraphNamespaceInfo>;
+    /** Non-destructive: set archived = true. `default` cannot be archived. */
+    archiveGraphNamespace?(namespace: string): Promise<boolean>;
+    /** Destructive: drop graph data for the exact namespace, then the registry
+     * row. Re-runnable. Never deletes source facts. `default` cannot be deleted. */
+    deleteGraphNamespace?(namespace: string): Promise<GraphNamespaceDeleteResult>;
+}
+/**
+ * Structural guard for the construction-time bundled-provider reuse decision
+ * only (a single provider object that backs both facts and graph). Graph TOOL
+ * gating is `!!graphStore` — a separate injection — never this sniff.
+ */
+export declare function isGraphStore(s: unknown): s is GraphStore;
+/**
+ * Whether a fact scope_key is readable under the given access context, decided
+ * purely from the key's shape: `shared:` always passes; `session:<id>:` passes
+ * iff `<id>` is the reader's or a granted session; unrestricted passes all.
+ * Used to filter graph `evidence` arrays and to ignore inaccessible seeds.
+ */
+export declare function scopeKeyAccessible(scopeKey: string, access?: AccessContext): boolean;
+//# sourceMappingURL=graph-store.d.ts.map

package/dist/graph-store.d.ts.map

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

package/dist/graph-store.js

@@ -0,0 +1,63 @@
+/**
+ * Graph Store — the OPTIONAL open knowledge graph contract (enhancedfactstore
+ * 07 D2).
+ *
+ * The graph is a SEPARATE, independently injected interface — NOT part of
+ * `EnhancedFactStore` and NOT a capability on the fact store. The SDK owns this
+ * contract; a concrete provider (e.g. pilotswarm-horizon-store's
+ * `HorizonDBGraphStore`, AGE-backed) implements it. The runtime registers graph
+ * tools iff a `graphStore` was injected (`!!graphStore`) — there is no
+ * fact-store sniff.
+ *
+ * The graph stores ids + structure only (never fact values or ACLs). Evidence
+ * scope_keys are opaque pointers; resolving them back to fact values is the
+ * caller's tool-layer composition:
+ *   graphStore.searchGraphNodes(...) -> scopeKeys -> factStore.readFacts({ scopeKeys })
+ *
+ * @module
+ */
+/**
+ * Reserved namespace token for the unscoped graph partition. Graph records with
+ * no namespace property (NULL) are the `default` partition: writes of `default`
+ * (or empty) store no namespace, and reads of `default` match `namespace IS
+ * NULL`. `default` is always present in the registry and cannot be archived or
+ * deleted (graph-fact-search enhancements).
+ */
+export const DEFAULT_GRAPH_NAMESPACE = "default";
+/**
+ * Structural guard for the construction-time bundled-provider reuse decision
+ * only (a single provider object that backs both facts and graph). Graph TOOL
+ * gating is `!!graphStore` — a separate injection — never this sniff.
+ */
+export function isGraphStore(s) {
+    return typeof s?.searchGraphNodes === "function"
+        && typeof s?.upsertGraphNode === "function"
+        && typeof s?.removeGraphEvidence === "function";
+}
+// ─── ACL helper (syntactic scope_key check) ──────────────────────────────────
+/**
+ * Whether a fact scope_key is readable under the given access context, decided
+ * purely from the key's shape: `shared:` always passes; `session:<id>:` passes
+ * iff `<id>` is the reader's or a granted session; unrestricted passes all.
+ * Used to filter graph `evidence` arrays and to ignore inaccessible seeds.
+ */
+export function scopeKeyAccessible(scopeKey, access) {
+    if (access?.unrestricted)
+        return true;
+    if (scopeKey.startsWith("shared:"))
+        return true;
+    if (scopeKey.startsWith("session:")) {
+        const rest = scopeKey.slice("session:".length);
+        // Require a real `<id>:<key>` shape; malformed keys fail closed.
+        const sep = rest.indexOf(":");
+        if (sep <= 0)
+            return false;
+        const sessionId = rest.slice(0, sep);
+        if (access?.readerSessionId && sessionId === access.readerSessionId)
+            return true;
+        if (access?.grantedSessionIds?.includes(sessionId))
+            return true;
+    }
+    return false;
+}
+//# sourceMappingURL=graph-store.js.map

package/dist/graph-store.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"graph-store.js","sourceRoot":"","sources":["../src/graph-store.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAIH;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,uBAAuB,GAAG,SAAS,CAAC;AAuOjD;;;;GAIG;AACH,MAAM,UAAU,YAAY,CAAC,CAAU;IACnC,OAAO,OAAQ,CAAS,EAAE,gBAAgB,KAAK,UAAU;WACtD,OAAQ,CAAS,EAAE,eAAe,KAAK,UAAU;WACjD,OAAQ,CAAS,EAAE,mBAAmB,KAAK,UAAU,CAAC;AAC7D,CAAC;AAED,gFAAgF;AAEhF;;;;;GAKG;AACH,MAAM,UAAU,kBAAkB,CAAC,QAAgB,EAAE,MAAsB;IACvE,IAAI,MAAM,EAAE,YAAY;QAAE,OAAO,IAAI,CAAC;IACtC,IAAI,QAAQ,CAAC,UAAU,CAAC,SAAS,CAAC;QAAE,OAAO,IAAI,CAAC;IAChD,IAAI,QAAQ,CAAC,UAAU,CAAC,UAAU,CAAC,EAAE,CAAC;QAClC,MAAM,IAAI,GAAG,QAAQ,CAAC,KAAK,CAAC,UAAU,CAAC,MAAM,CAAC,CAAC;QAC/C,iEAAiE;QACjE,MAAM,GAAG,GAAG,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC;QAC9B,IAAI,GAAG,IAAI,CAAC;YAAE,OAAO,KAAK,CAAC;QAC3B,MAAM,SAAS,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC;QACrC,IAAI,MAAM,EAAE,eAAe,IAAI,SAAS,KAAK,MAAM,CAAC,eAAe;YAAE,OAAO,IAAI,CAAC;QACjF,IAAI,MAAM,EAAE,iBAAiB,EAAE,QAAQ,CAAC,SAAS,CAAC;YAAE,OAAO,IAAI,CAAC;IACpE,CAAC;IACD,OAAO,KAAK,CAAC;AACjB,CAAC"}

package/dist/graph-tools.d.ts

@@ -0,0 +1,47 @@
+import type { Tool } from "@github/copilot-sdk";
+import type { AccessContext, FactStore } from "./facts-store.js";
+import type { GraphStore } from "./graph-store.js";
+export interface CreateGraphToolsOptions {
+    graphStore: GraphStore;
+    /** Base fact store — graph_stats reads crawl-queue counts from it. */
+    factStore: FactStore;
+    /** The session's agent identity, used for role gating. */
+    agentIdentity?: string;
+    /**
+     * Whether this session holds the app-assigned HARVESTER role. This now gates
+     * ONLY the crawl work queue (`facts_read_uncrawled` / `facts_mark_crawled`);
+     * the facts-manager additionally receives the queue (dormant), and
+     * agent-tuner never does. Graph write/delete is NOT gated by this flag — it
+     * is available to every non-tuner session (see `canWriteGraph`).
+     */
+    isHarvester?: boolean;
+    /**
+     * Resolve the caller's ACL context for graph reads (evidence filtering +
+     * seed gating). REQUIRED for correct isolation: without it, a reader would
+     * see every session's evidence. Mirrors the read_facts lineage model —
+     * returns { readerSessionId, grantedSessionIds } (or { unrestricted: true }
+     * for the tuner). If omitted, graph reads FAIL CLOSED to the caller's own
+     * session only (never unrestricted).
+     */
+    resolveAccess?: (sessionId: string | undefined) => Promise<AccessContext>;
+    /** Agent id recorded on graph writes. */
+    agentId?: string;
+    /**
+     * Fire-and-forget hook recording a `graph.searched` event (query + result
+     * digest) for tuner forensics (07 P4 observability). Errors swallowed.
+     */
+    recordEvent?: (sessionId: string, eventType: string, data: unknown) => Promise<void>;
+}
+/**
+ * Build the graph + crawl-queue tools (enhancedfactstore 07 P4). Registered
+ * ONLY when a `graphStore` is present. Reader tools (search/neighbourhood) go to
+ * every session; graph write/delete (`graph_upsert_*` / `graph_merge_nodes` /
+ * `graph_delete_*`) go to EVERY session EXCEPT the read-only agent-tuner, so any
+ * agent can incorporate into the SHARED graph; the crawl work queue
+ * (`facts_read_uncrawled` / `facts_mark_crawled`) stays harvester-role +
+ * facts-manager only (it reads facts across ALL scopes, bypassing per-session
+ * ACL); `graph_stats` (read-only) goes to facts-manager + agent-tuner.
+ * agent-tuner never gets a mutating tool.
+ */
+export declare function createGraphTools(opts: CreateGraphToolsOptions): Tool<any>[];
+//# sourceMappingURL=graph-tools.d.ts.map

package/dist/graph-tools.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"graph-tools.d.ts","sourceRoot":"","sources":["../src/graph-tools.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,qBAAqB,CAAC;AAChD,OAAO,KAAK,EAAE,aAAa,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AACjE,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAwCnD,MAAM,WAAW,uBAAuB;IACpC,UAAU,EAAE,UAAU,CAAC;IACvB,sEAAsE;IACtE,SAAS,EAAE,SAAS,CAAC;IACrB,0DAA0D;IAC1D,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB;;;;;;OAMG;IACH,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB;;;;;;;OAOG;IACH,aAAa,CAAC,EAAE,CAAC,SAAS,EAAE,MAAM,GAAG,SAAS,KAAK,OAAO,CAAC,aAAa,CAAC,CAAC;IAC1E,yCAAyC;IACzC,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB;;;OAGG;IACH,WAAW,CAAC,EAAE,CAAC,SAAS,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;CACxF;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,uBAAuB,GAAG,IAAI,CAAC,GAAG,CAAC,EAAE,CAqiB3E"}