@treeseed/sdk 0.1.2 → 0.3.1

package/dist/graph/schema.js

@@ -0,0 +1,133 @@
+import crypto from "node:crypto";
+import path from "node:path";
+const GRAPH_SNAPSHOT_VERSION = 1;
+const AUTHORED_GRAPH_EDGE_TYPES = [
+  "REFERENCES",
+  "HAS_TAG",
+  "IN_SERIES",
+  "RELATES_TO",
+  "DEPENDS_ON",
+  "IMPLEMENTS",
+  "EXTENDS",
+  "SUPERSEDES",
+  "BELONGS_TO",
+  "ABOUT",
+  "USED_BY",
+  "GENERATED_FROM"
+];
+function sha1(value) {
+  return crypto.createHash("sha1").update(value).digest("hex");
+}
+function computeEdgeId(sourceId, edgeType, targetId, provenance = "") {
+  return `edge:${sha1(`${sourceId}|${edgeType}|${targetId}|${provenance}`)}`;
+}
+function createFileNodeId(model, slug) {
+  return `file:${model}:${slug}`;
+}
+function createEntityNodeId(definition, slug, frontmatter) {
+  const explicitId = typeof frontmatter.id === "string" && frontmatter.id.trim() ? frontmatter.id.trim() : null;
+  return explicitId ?? `entity:${definition.name}:${slug}`;
+}
+function normalizeText(value) {
+  return value.replace(/\s+/g, " ").trim().toLowerCase();
+}
+function ensureArray(value) {
+  if (Array.isArray(value)) {
+    return value.map((entry) => typeof entry === "string" ? entry.trim() : "").filter(Boolean);
+  }
+  if (typeof value === "string" && value.trim()) {
+    return [value.trim()];
+  }
+  return [];
+}
+function builtinEntityTypeFor(model) {
+  switch (model) {
+    case "agent":
+      return "Agent";
+    case "objective":
+      return "Objective";
+    case "question":
+      return "Question";
+    case "note":
+      return "Note";
+    case "knowledge":
+      return "Knowledge";
+    case "book":
+      return "Book";
+    case "page":
+      return "Page";
+    case "person":
+      return "Person";
+    default:
+      return "Entity";
+  }
+}
+function resolveGraphModelConfig(definition) {
+  return {
+    entityType: definition.graph?.entityType ?? builtinEntityTypeFor(definition.name),
+    referenceFields: definition.graph?.referenceFields ?? [],
+    tagField: definition.graph?.tagField ?? (definition.fields.tags ? "tags" : ""),
+    seriesField: definition.graph?.seriesField ?? "",
+    titleField: definition.graph?.titleField ?? (definition.fields.title ? "title" : definition.fields.name ? "name" : "title"),
+    enableSections: definition.graph?.enableSections ?? true
+  };
+}
+function computeModelSignature(models) {
+  const contentModels = Object.values(models).filter((definition) => definition.storage === "content" && definition.contentDir).map((definition) => ({
+    name: definition.name,
+    contentDir: definition.contentDir,
+    contentCollection: definition.contentCollection ?? null,
+    fields: Object.keys(definition.fields).sort(),
+    graph: resolveGraphModelConfig(definition)
+  })).sort((left, right) => left.name.localeCompare(right.name));
+  return sha1(JSON.stringify(contentModels));
+}
+function graphSnapshotRoot(repoRoot) {
+  return path.join(repoRoot, ".treeseed", "state", "graph");
+}
+function emptyGraphMetrics() {
+  return {
+    totalFiles: 0,
+    totalSections: 0,
+    totalEntities: 0,
+    totalEdges: 0,
+    unresolvedReferences: 0,
+    validation: {
+      missingIds: 0,
+      duplicateIds: 0,
+      brokenReferences: 0,
+      invalidEdgeTypes: 0,
+      invalidCanonicalRefs: 0,
+      invalidSupersedesRefs: 0
+    },
+    queryCounts: {},
+    topTraversedEdgeTypes: {},
+    lastRefreshAt: null
+  };
+}
+function emptyGraphValidation() {
+  return {
+    missingIds: [],
+    duplicateIds: [],
+    brokenReferences: [],
+    invalidEdgeTypes: [],
+    invalidCanonicalRefs: [],
+    invalidSupersedesRefs: []
+  };
+}
+export {
+  AUTHORED_GRAPH_EDGE_TYPES,
+  GRAPH_SNAPSHOT_VERSION,
+  builtinEntityTypeFor,
+  computeEdgeId,
+  computeModelSignature,
+  createEntityNodeId,
+  createFileNodeId,
+  emptyGraphMetrics,
+  emptyGraphValidation,
+  ensureArray,
+  graphSnapshotRoot,
+  normalizeText,
+  resolveGraphModelConfig,
+  sha1
+};

package/dist/graph.d.ts

@@ -0,0 +1,52 @@
+import type { SdkContextPack, SdkContextPackRequest, SdkGraphPathExplanation, SdkGraphDslParseResult, SdkGraphQueryOptions, SdkGraphQueryRequest, SdkGraphQueryResult, SdkGraphRefreshPayload, SdkGraphRefreshRequest, SdkGraphSearchOptions, SdkGraphSearchResult, SdkGraphSeedResolution, SdkGraphTraversalResult, SdkModelRegistry, SdkGraphRankingProvider } from './sdk-types.ts';
+import type { LoadedTreeseedPluginEntry } from './platform/plugins.ts';
+export interface ContentGraphRuntimeOptions {
+    rankingProvider?: SdkGraphRankingProvider;
+    plugins?: LoadedTreeseedPluginEntry[];
+}
+/** Advanced direct graph runtime used internally by AgentSdk and available for low-level integrations. */
+export declare class ContentGraphRuntime {
+    private readonly repoRoot;
+    private readonly models;
+    private state;
+    private queryEngine;
+    private readonly rankingProvider;
+    constructor(repoRoot: string, models: SdkModelRegistry, options?: ContentGraphRuntimeOptions);
+    private trackQuery;
+    private ensureLoaded;
+    private persist;
+    refresh(request?: SdkGraphRefreshRequest): Promise<SdkGraphRefreshPayload>;
+    /** Advanced lexical graph primitive for file nodes. */
+    searchFiles(query: string, options?: SdkGraphSearchOptions): Promise<SdkGraphSearchResult[]>;
+    /** Advanced lexical graph primitive for section nodes. */
+    searchSections(query: string, options?: SdkGraphSearchOptions): Promise<SdkGraphSearchResult[]>;
+    /** Advanced lexical graph primitive for entity nodes. */
+    searchEntities(query: string, options?: SdkGraphSearchOptions): Promise<SdkGraphSearchResult[]>;
+    getNode(id: string): Promise<import("./sdk-types.ts").SdkGraphNode | null>;
+    getNeighbors(id: string, options?: SdkGraphQueryOptions): Promise<{
+        node: import("./sdk-types.ts").SdkGraphNode | null;
+        nodes: import("./sdk-types.ts").SdkGraphNode[];
+        edges: import("./sdk-types.ts").SdkGraphEdge[];
+    }>;
+    followReferences(id: string, options?: SdkGraphQueryOptions): Promise<SdkGraphTraversalResult>;
+    getBacklinks(id: string, options?: SdkGraphQueryOptions): Promise<{
+        node: import("./sdk-types.ts").SdkGraphNode | null;
+        nodes: import("./sdk-types.ts").SdkGraphNode[];
+        edges: import("./sdk-types.ts").SdkGraphEdge[];
+    }>;
+    getRelated(id: string, options?: SdkGraphQueryOptions): Promise<import("./sdk-types.ts").SdkGraphQueryNodeResult[]>;
+    getSubgraph(seedIds: string[], options?: SdkGraphQueryOptions): Promise<SdkGraphTraversalResult>;
+    resolveSeeds(request: SdkGraphQueryRequest): Promise<SdkGraphSeedResolution>;
+    /** Preferred ranked graph retrieval entrypoint when using the graph runtime directly. */
+    queryGraph(request: SdkGraphQueryRequest): Promise<SdkGraphQueryResult>;
+    /** Preferred prompt-ready context assembly entrypoint when using the graph runtime directly. */
+    buildContextPack(request: SdkContextPackRequest): Promise<SdkContextPack>;
+    /** Parses the public ctx DSL into a typed graph request. */
+    parseGraphDsl(source: string): Promise<SdkGraphDslParseResult>;
+    resolveReference(reference: string, options?: {
+        fromNodeId?: string;
+        fromPath?: string;
+        models?: string[];
+    }): Promise<import("./sdk-types.ts").SdkGraphNode | null>;
+    explainReferenceChain(fromId: string, toId: string): Promise<SdkGraphPathExplanation | null>;
+}

package/dist/graph.js

@@ -0,0 +1,133 @@
+import { writeFile } from "node:fs/promises";
+import path from "node:path";
+import { loadGraphSnapshot, refreshGraphBuildState, saveGraphSnapshot } from "./graph/build.js";
+import { GraphQueryEngine } from "./graph/query.js";
+import { DEFAULT_GRAPH_RANKING_PROVIDER } from "./graph/ranking.js";
+import { resolveTreeseedGraphRankingProvider } from "./platform/plugins.js";
+class ContentGraphRuntime {
+  constructor(repoRoot, models, options = {}) {
+    this.repoRoot = repoRoot;
+    this.models = models;
+    this.rankingProvider = options.rankingProvider ?? (options.plugins?.length ? resolveTreeseedGraphRankingProvider(options.plugins, { projectRoot: repoRoot }) ?? DEFAULT_GRAPH_RANKING_PROVIDER : DEFAULT_GRAPH_RANKING_PROVIDER);
+  }
+  repoRoot;
+  models;
+  state = null;
+  queryEngine = null;
+  rankingProvider;
+  trackQuery(name, detail) {
+    if (!this.state) {
+      return;
+    }
+    this.state.metrics.queryCounts[name] = (this.state.metrics.queryCounts[name] ?? 0) + 1;
+    if (detail && name === "followReferences") {
+      const edgeType = detail.split(":")[0] ?? "follow";
+      this.state.metrics.topTraversedEdgeTypes[edgeType] = (this.state.metrics.topTraversedEdgeTypes[edgeType] ?? 0) + 1;
+    }
+  }
+  async ensureLoaded() {
+    if (this.state && this.queryEngine) {
+      return;
+    }
+    this.state = await loadGraphSnapshot(this.repoRoot, this.models);
+    if (!this.state) {
+      this.state = await refreshGraphBuildState(this.repoRoot, this.models);
+      await this.persist();
+    }
+    this.queryEngine = new GraphQueryEngine(this.state, (name, detail) => this.trackQuery(name, detail), this.rankingProvider);
+  }
+  async persist() {
+    if (!this.state || !this.queryEngine) {
+      return;
+    }
+    await saveGraphSnapshot(this.state);
+    const serializedIndexes = this.queryEngine.serializeIndexes();
+    await writeFile(
+      path.join(this.state.snapshotRoot, "indexes.json"),
+      `${JSON.stringify(serializedIndexes, null, 2)}
+`,
+      "utf8"
+    );
+  }
+  async refresh(request) {
+    await this.ensureLoaded();
+    this.state = await refreshGraphBuildState(this.repoRoot, this.models, request, this.state);
+    this.queryEngine = new GraphQueryEngine(this.state, (name, detail) => this.trackQuery(name, detail), this.rankingProvider);
+    await this.persist();
+    return {
+      ready: true,
+      snapshotRoot: this.state.snapshotRoot,
+      changed: this.state.delta,
+      metrics: this.state.metrics
+    };
+  }
+  /** Advanced lexical graph primitive for file nodes. */
+  async searchFiles(query, options) {
+    await this.ensureLoaded();
+    return this.queryEngine.searchFiles(query, options);
+  }
+  /** Advanced lexical graph primitive for section nodes. */
+  async searchSections(query, options) {
+    await this.ensureLoaded();
+    return this.queryEngine.searchSections(query, options);
+  }
+  /** Advanced lexical graph primitive for entity nodes. */
+  async searchEntities(query, options) {
+    await this.ensureLoaded();
+    return this.queryEngine.searchEntities(query, options);
+  }
+  async getNode(id) {
+    await this.ensureLoaded();
+    return this.queryEngine.getNode(id);
+  }
+  async getNeighbors(id, options) {
+    await this.ensureLoaded();
+    return this.queryEngine.getNeighbors(id, options);
+  }
+  async followReferences(id, options) {
+    await this.ensureLoaded();
+    return this.queryEngine.followReferences(id, options);
+  }
+  async getBacklinks(id, options) {
+    await this.ensureLoaded();
+    return this.queryEngine.getBacklinks(id, options);
+  }
+  async getRelated(id, options) {
+    await this.ensureLoaded();
+    return this.queryEngine.getRelated(id, options);
+  }
+  async getSubgraph(seedIds, options) {
+    await this.ensureLoaded();
+    return this.queryEngine.getSubgraph(seedIds, options);
+  }
+  async resolveSeeds(request) {
+    await this.ensureLoaded();
+    return this.queryEngine.resolveSeeds(request);
+  }
+  /** Preferred ranked graph retrieval entrypoint when using the graph runtime directly. */
+  async queryGraph(request) {
+    await this.ensureLoaded();
+    return this.queryEngine.queryGraph(request);
+  }
+  /** Preferred prompt-ready context assembly entrypoint when using the graph runtime directly. */
+  async buildContextPack(request) {
+    await this.ensureLoaded();
+    return this.queryEngine.buildContextPack(request);
+  }
+  /** Parses the public ctx DSL into a typed graph request. */
+  async parseGraphDsl(source) {
+    await this.ensureLoaded();
+    return this.queryEngine.parseDsl(source);
+  }
+  async resolveReference(reference, options) {
+    await this.ensureLoaded();
+    return this.queryEngine.resolveReference(reference, options);
+  }
+  async explainReferenceChain(fromId, toId) {
+    await this.ensureLoaded();
+    return this.queryEngine.explainReferenceChain(fromId, toId);
+  }
+}
+export {
+  ContentGraphRuntime
+};

package/dist/index.d.ts

@@ -0,0 +1,28 @@
+export { AgentSdk, ScopedAgentSdk } from './sdk.ts';
+export { ContentGraphRuntime } from './graph.ts';
+export { parseGraphDsl } from './graph/dsl.ts';
+export { createDefaultGraphRankingProvider, DEFAULT_GRAPH_RANKING_PROVIDER } from './graph/ranking.ts';
+export { BUILTIN_MODEL_REGISTRY, MODEL_REGISTRY, buildBuiltinModelRegistry, buildModelRegistry, buildScopedModelRegistry, mergeModelRegistries, resolveModelDefinition, } from './model-registry.ts';
+export { normalizeAgentCliOptions, buildCopilotAllowToolArgs } from './cli-tools.ts';
+export { resolveSdkRecordVersion } from './sdk-version.ts';
+export { normalizeAliasedRecord, preprocessAliasedRecord, resolveAliasedField, } from './field-aliases.ts';
+export { canonicalizeFrontmatter, normalizeFilterFields, normalizeMutationData, normalizeRecordToCanonicalShape, normalizeSortFields, readCanonicalFieldValue, resolveModelField, validateModelFieldAliases, } from './sdk-fields.ts';
+export { RemoteTemplateCatalogClient, parseTemplateCatalogResponse } from './template-catalog.ts';
+export { TREESEED_REMOTE_CONTRACT_HEADER, TREESEED_REMOTE_CONTRACT_VERSION, CloudflareQueuePullClient, RemoteTreeseedClient, RemoteTreeseedAuthClient, RemoteTreeseedSdkClient, RemoteTreeseedOperationsClient, TreeseedGatewayClient, } from './remote.ts';
+export { TRESEED_OPERATION_SPECS, findTreeseedOperation, listTreeseedOperationNames, } from './operations-registry.ts';
+export { TreeseedOperationsSdk } from './operations/runtime.ts';
+export { TreeseedWorkflowSdk } from './workflow.ts';
+export { getTreeseedVerifyDriverStatus, runTreeseedVerifyDriver } from './verification.ts';
+export * from './platform/contracts.ts';
+export * from './platform/tenant-config.ts';
+export * from './platform/deploy-config.ts';
+export * from './platform/deploy-runtime.ts';
+export * from './platform/environment.ts';
+export * from './platform/plugins.ts';
+export type { SdkContentEntry, SdkCursorEntity, SdkFilterCondition, SdkFollowRequest, SdkGraphEdge, SdkGraphEdgeType, SdkGraphDslRelation, SdkGraphDslParseResult, SdkGraphModelConfig, SdkGraphNode, SdkGraphNodeType, SdkGraphPathExplanation, SdkGraphQueryStage, SdkGraphQueryView, SdkGraphQueryOptions, SdkGraphQueryRequest, SdkGraphQueryResult, SdkGraphRankingBuildInput, SdkGraphRankingDiagnostics, SdkGraphRankingIndex, SdkGraphRankingNodeResult, SdkGraphRankingProvider, SdkGraphRankingQueryRequest, SdkGraphRankingQueryResult, SdkGraphRankingSearchRequest, SdkGraphRefreshPayload, SdkGraphRefreshRequest, SdkGraphSearchOptions, SdkGraphSearchResult, SdkGraphSeed, SdkGraphSeedResolution, SdkGraphTraversalResult, SdkGraphWhereFilter, SdkContextPack, SdkContextPackRequest, SdkGetRequest, SdkJsonEnvelope, SdkLeaseEntity, SdkManagerContextPayload, SdkMessageEntity, SdkModelFieldBinding, SdkModelDefinition, SdkModelRegistry, SdkModelName, SdkMutationRequest, SdkOperation, SdkPickRequest, SdkPickResult, SdkQueueMessageEnvelope, SdkRunEntity, SdkSearchRequest, SdkTaskEntity, SdkTaskEventEntity, SdkTaskOutputEntity, SdkWorkDayEntity, SdkGraphRunEntity, SdkReportEntity, SdkSubscriptionEntity, SdkTemplateCatalogEntry, SdkTemplateCatalogPublisher, SdkTemplateCatalogResponse, SdkTemplateCatalogSource, SdkUpdateRequest, } from './sdk-types.ts';
+export type { TreeseedFieldAliasBinding, TreeseedFieldAliasRegistry, } from './field-aliases.ts';
+export type { TreeseedOperationContext, TreeseedOperationGroup, TreeseedOperationImplementation, TreeseedOperationId, TreeseedOperationMetadata, TreeseedOperationProvider, TreeseedOperationProviderId, TreeseedOperationRequest, TreeseedOperationResult, } from './operations-types.ts';
+export type * from './workflow.ts';
+export type { AgentDatabase } from './d1-store.ts';
+export type { D1DatabaseLike, D1PreparedStatementLike } from './types/cloudflare.ts';
+export type * from './remote.ts';

package/dist/index.js

@@ -1,12 +1,101 @@
 import { AgentSdk, ScopedAgentSdk } from "./sdk.js";
-import { MODEL_REGISTRY, buildModelRegistry, resolveModelDefinition } from "./model-registry.js";
+import { ContentGraphRuntime } from "./graph.js";
+import { parseGraphDsl } from "./graph/dsl.js";
+import { createDefaultGraphRankingProvider, DEFAULT_GRAPH_RANKING_PROVIDER } from "./graph/ranking.js";
+import {
+  BUILTIN_MODEL_REGISTRY,
+  MODEL_REGISTRY,
+  buildBuiltinModelRegistry,
+  buildModelRegistry,
+  buildScopedModelRegistry,
+  mergeModelRegistries,
+  resolveModelDefinition
+} from "./model-registry.js";
 import { normalizeAgentCliOptions, buildCopilotAllowToolArgs } from "./cli-tools.js";
+import { resolveSdkRecordVersion } from "./sdk-version.js";
+import {
+  normalizeAliasedRecord,
+  preprocessAliasedRecord,
+  resolveAliasedField
+} from "./field-aliases.js";
+import {
+  canonicalizeFrontmatter,
+  normalizeFilterFields,
+  normalizeMutationData,
+  normalizeRecordToCanonicalShape,
+  normalizeSortFields,
+  readCanonicalFieldValue,
+  resolveModelField,
+  validateModelFieldAliases
+} from "./sdk-fields.js";
+import { RemoteTemplateCatalogClient, parseTemplateCatalogResponse } from "./template-catalog.js";
+import {
+  TREESEED_REMOTE_CONTRACT_HEADER,
+  TREESEED_REMOTE_CONTRACT_VERSION,
+  CloudflareQueuePullClient,
+  RemoteTreeseedClient,
+  RemoteTreeseedAuthClient,
+  RemoteTreeseedSdkClient,
+  RemoteTreeseedOperationsClient,
+  TreeseedGatewayClient
+} from "./remote.js";
+import {
+  TRESEED_OPERATION_SPECS,
+  findTreeseedOperation,
+  listTreeseedOperationNames
+} from "./operations-registry.js";
+import { TreeseedOperationsSdk } from "./operations/runtime.js";
+import { TreeseedWorkflowSdk } from "./workflow.js";
+import { getTreeseedVerifyDriverStatus, runTreeseedVerifyDriver } from "./verification.js";
+export * from "./platform/contracts.js";
+export * from "./platform/tenant-config.js";
+export * from "./platform/deploy-config.js";
+export * from "./platform/deploy-runtime.js";
+export * from "./platform/environment.js";
+export * from "./platform/plugins.js";
 export {
   AgentSdk,
+  BUILTIN_MODEL_REGISTRY,
+  CloudflareQueuePullClient,
+  ContentGraphRuntime,
+  DEFAULT_GRAPH_RANKING_PROVIDER,
   MODEL_REGISTRY,
+  RemoteTemplateCatalogClient,
+  RemoteTreeseedAuthClient,
+  RemoteTreeseedClient,
+  RemoteTreeseedOperationsClient,
+  RemoteTreeseedSdkClient,
   ScopedAgentSdk,
+  TREESEED_REMOTE_CONTRACT_HEADER,
+  TREESEED_REMOTE_CONTRACT_VERSION,
+  TRESEED_OPERATION_SPECS,
+  TreeseedGatewayClient,
+  TreeseedOperationsSdk,
+  TreeseedWorkflowSdk,
+  buildBuiltinModelRegistry,
   buildCopilotAllowToolArgs,
   buildModelRegistry,
+  buildScopedModelRegistry,
+  canonicalizeFrontmatter,
+  createDefaultGraphRankingProvider,
+  findTreeseedOperation,
+  getTreeseedVerifyDriverStatus,
+  listTreeseedOperationNames,
+  mergeModelRegistries,
   normalizeAgentCliOptions,
-  resolveModelDefinition
+  normalizeAliasedRecord,
+  normalizeFilterFields,
+  normalizeMutationData,
+  normalizeRecordToCanonicalShape,
+  normalizeSortFields,
+  parseGraphDsl,
+  parseTemplateCatalogResponse,
+  preprocessAliasedRecord,
+  readCanonicalFieldValue,
+  resolveAliasedField,
+  resolveModelDefinition,
+  resolveModelField,
+  resolveSdkRecordVersion,
+  runTreeseedVerifyDriver,
+  validateModelFieldAliases
 };

package/dist/model-registry.d.ts

@@ -0,0 +1,8 @@
+import type { SdkBuiltinModelName, SdkModelDefinition, SdkModelRegistry } from './sdk-types.ts';
+export declare function buildBuiltinModelRegistry(repoRoot?: string): Record<SdkBuiltinModelName, SdkModelDefinition>;
+export declare function mergeModelRegistries(baseRegistry: SdkModelRegistry, definitions?: SdkModelDefinition[]): SdkModelRegistry;
+export declare function buildModelRegistry(definitions?: SdkModelDefinition[]): SdkModelRegistry;
+export declare function buildScopedModelRegistry(repoRoot: string | undefined, definitions?: SdkModelDefinition[]): SdkModelRegistry;
+export declare const BUILTIN_MODEL_REGISTRY: SdkModelRegistry;
+export declare const MODEL_REGISTRY: SdkModelRegistry;
+export declare function resolveModelDefinition(model: string, registry?: SdkModelRegistry): SdkModelDefinition;