@decantr/core 2.1.0 → 3.0.0-next.0

package/README.md

@@ -25,9 +25,12 @@ npm install @decantr/core
 - execution-pack schema URLs
 - markdown rendering for compiled packs
 - IR and pipeline helpers used by higher-level Decantr surfaces
+- draft Decantr 3 typed graph types, graph constants, Essence/IR-to-graph snapshot derivation, temporal snapshot/diff shapes, source import/reference edges, contract capsule derivation with a bounded source-artifact path index, task-aware route-context ranking, node impact context extraction, and an in-memory `GraphStore` adapter for early graph-foundation work
 
 In the current workflow architecture, `@decantr/core` owns the canonical adapter labels used by compiled packs, while runnable greenfield bootstrap adapters are resolved in the CLI on top of those labels.
 
+The graph exports are draft Decantr 3 foundation APIs. They establish the storage boundary, typed schema shape, temporal snapshot/diff shape, payload-filterable node queries, task-aware route-context ranking, node impact traversal, and provider-neutral contract capsule shape for CLI, MCP, verifier, and CI integration. The capsule keeps the contract cache key stable while listing bounded SourceArtifact paths agents can use for file-impact follow-up queries. The core package remains pure library code: filesystem graph persistence belongs in higher-level packages such as the CLI.
+
 ## FAQ
 
 Most teams should start with the CLI rather than this low-level package:
@@ -73,6 +76,18 @@ This package publishes execution-pack schemas under:
 - `@decantr/core/schema/execution-pack-bundle.v1.json`
 - `@decantr/core/schema/selected-execution-pack.v1.json`
 
+It also publishes the draft Decantr 3 typed graph artifact schemas:
+
+- `@decantr/core/schema/graph.common.v1.json`
+- `@decantr/core/schema/graph-snapshot.v1.json`
+- `@decantr/core/schema/graph-manifest.v1.json`
+- `@decantr/core/schema/graph-diff.v1.json`
+- `@decantr/core/schema/contract-capsule.v1.json`
+
+## Security And Permissions
+
+`@decantr/core` is a local execution-pack compiler and type/schema package. It does not read or write project files, call the network, spawn processes, emit telemetry, or upload source by itself. The draft graph exports include pure builders and an in-memory adapter only; filesystem graph persistence belongs in higher-level CLI/verifier wiring. Schema URLs in emitted packs are identifiers, not network calls. See [security permissions](https://decantr.ai/reference/security-permissions.md).
+
 ## License
 
 MIT

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import { StructurePage, EssenceFile, EssenceV4 } from '@decantr/essence-spec';
+import { EssenceV4, StructurePage, EssenceFile } from '@decantr/essence-spec';
 import { Pattern, ResolvedPreset, Theme, ContentResolver } from '@decantr/registry';
 
 type IRNodeType = 'app' | 'shell' | 'page' | 'pattern' | 'grid' | 'nav' | 'store';
@@ -150,6 +150,369 @@ interface IRStoreNode extends IRNode {
     }[];
 }
 
+declare const GRAPH_SCHEMA_VERSION = "3.0.0-draft";
+declare const GRAPH_COMMON_SCHEMA_URL = "https://decantr.ai/schemas/graph.common.v1.json";
+declare const GRAPH_SNAPSHOT_SCHEMA_URL = "https://decantr.ai/schemas/graph-snapshot.v1.json";
+declare const GRAPH_MANIFEST_SCHEMA_URL = "https://decantr.ai/schemas/graph-manifest.v1.json";
+declare const GRAPH_DIFF_SCHEMA_URL = "https://decantr.ai/schemas/graph-diff.v1.json";
+declare const CONTRACT_CAPSULE_SCHEMA_URL = "https://decantr.ai/schemas/contract-capsule.v1.json";
+declare const DEFAULT_CONTRACT_CAPSULE_SOURCE_ARTIFACT_LIMIT = 200;
+declare const GRAPH_NODE_TYPES: readonly ["Project", "Section", "Page", "Route", "Shell", "Region", "Pattern", "Component", "Token", "Theme", "Decorator", "Feature", "LocalRule", "StyleBridge", "SourceArtifact", "Finding", "Evidence", "Repair", "Test", "AgentRun"];
+type GraphNodeType = (typeof GRAPH_NODE_TYPES)[number];
+declare const GRAPH_RELATIONS: readonly ["PROJECT_CONTAINS_SECTION", "PROJECT_ENABLES_FEATURE", "PROJECT_USES_THEME", "SECTION_CONTAINS_PAGE", "PAGE_ROUTED_AT_ROUTE", "PAGE_USES_SHELL", "SHELL_HAS_REGION", "PAGE_COMPOSES_PATTERN", "PATTERN_NEEDS_COMPONENT", "COMPONENT_STYLED_WITH_TOKEN", "THEME_DEFINES_TOKEN", "THEME_DEFINES_DECORATOR", "COMPONENT_DECORATED_WITH_DECORATOR", "LOCAL_RULE_APPLIES_TO", "STYLE_BRIDGE_MAPS_TO", "NODE_DERIVED_FROM_SOURCE", "SOURCE_IMPORTS_SOURCE", "FINDING_VIOLATES_RULE", "FINDING_ANCHORED_AT", "EVIDENCE_SUPPORTS_FINDING", "EVIDENCE_CAPTURED_FOR", "REPAIR_FIXES_FINDING", "TEST_COVERS_NODE", "AGENT_RUN_CHANGED_NODE"];
+type GraphRelation = (typeof GRAPH_RELATIONS)[number];
+type GraphDiffOpType = 'node.added' | 'node.removed' | 'node.changed' | 'edge.added' | 'edge.removed' | 'edge.changed' | 'finding.added' | 'finding.resolved' | 'evidence.added';
+interface GraphNode<TPayload = unknown> {
+    id: string;
+    type: GraphNodeType;
+    payload: TPayload;
+    created_at?: string;
+    updated_at?: string;
+}
+interface GraphEdge<TPayload = unknown> {
+    src: string;
+    dst: string;
+    relation: GraphRelation;
+    payload?: TPayload;
+    idx?: number;
+}
+interface SourceArtifact {
+    id: string;
+    kind: string;
+    path?: string;
+    commit?: string;
+    hash?: string;
+    payload?: Record<string, unknown>;
+}
+interface GraphSnapshot {
+    $schema?: string;
+    id: string;
+    schema_version: string;
+    project_id: string;
+    created_at: string;
+    parent_id?: string;
+    source_hash: string;
+    git?: {
+        commit?: string;
+        branch?: string;
+        dirty?: boolean;
+    };
+    nodes: GraphNode[];
+    edges: GraphEdge[];
+    summary: {
+        nodes: number;
+        edges: number;
+        findings: number;
+        evidence: number;
+    };
+}
+interface GraphManifest {
+    $schema?: string;
+    schema_version: string;
+    snapshot_id: string;
+    project_id: string;
+    generated_at: string;
+    sources: SourceArtifact[];
+    outputs: {
+        sqlite?: string;
+        snapshot: string;
+        history?: string;
+        diff?: string;
+    };
+    warnings: Array<{
+        code: string;
+        message: string;
+    }>;
+}
+interface GraphDiffOp {
+    op: GraphDiffOpType;
+    id?: string;
+    type?: GraphNodeType;
+    src?: string;
+    dst?: string;
+    relation?: GraphRelation;
+    before?: unknown;
+    after?: unknown;
+}
+interface GraphDiff {
+    $schema?: string;
+    id: string;
+    from?: string;
+    to: string;
+    ops: GraphDiffOp[];
+}
+interface GraphDiffSummary {
+    total: number;
+    by_type: Record<GraphDiffOpType, number>;
+    nodes: {
+        added: number;
+        removed: number;
+        changed: number;
+    };
+    edges: {
+        added: number;
+        removed: number;
+        changed: number;
+    };
+    findings: {
+        added: number;
+        resolved: number;
+    };
+    evidence: {
+        added: number;
+    };
+}
+interface GraphFinding {
+    id: string;
+    code: string;
+    severity: 'blocker' | 'error' | 'warn' | 'info';
+    category: string;
+    anchored_at?: string;
+    violates?: string[];
+    derived_from?: string[];
+    message: string;
+    payload?: Record<string, unknown>;
+    evidence?: string[];
+    baseline?: {
+        snapshot_id?: string;
+        commit?: string;
+    };
+    repair?: {
+        id: string;
+        payload?: Record<string, unknown>;
+    };
+}
+interface ContractCapsuleRoute {
+    id: string;
+    path: string;
+    page_id?: string;
+    shell_id?: string;
+}
+interface ContractCapsuleVocabularyItem {
+    id: string;
+    label?: string;
+    payload?: unknown;
+}
+interface ContractCapsuleSourceArtifact {
+    id: string;
+    path: string;
+    kind?: string;
+    label?: string;
+    payload?: unknown;
+}
+interface ContractCapsuleFinding {
+    id: string;
+    code?: string;
+    severity?: string;
+    anchored_at?: string;
+    message?: string;
+}
+interface ContractCapsule {
+    $schema?: string;
+    schema_version: string;
+    snapshot_id: string;
+    project_id: string;
+    created_at: string;
+    source_hash: string;
+    contract_hash?: string;
+    cache_key: string;
+    contract_cache_key?: string;
+    summary: {
+        routes: number;
+        components: number;
+        tokens: number;
+        local_rules: number;
+        style_bridge: number;
+        source_artifacts: number;
+        open_findings: number;
+    };
+    source_artifact_limit: number;
+    source_artifacts_truncated: boolean;
+    routes: ContractCapsuleRoute[];
+    components: ContractCapsuleVocabularyItem[];
+    tokens: ContractCapsuleVocabularyItem[];
+    local_rules: ContractCapsuleVocabularyItem[];
+    style_bridge: ContractCapsuleVocabularyItem[];
+    source_artifacts: ContractCapsuleSourceArtifact[];
+    open_findings: ContractCapsuleFinding[];
+}
+interface BuildContractCapsuleOptions {
+    createdAt?: string;
+    cacheKey?: string;
+    sourceArtifactLimit?: number;
+}
+interface GraphNodeQuery {
+    ids?: string[];
+    type?: GraphNodeType;
+    types?: GraphNodeType[];
+    payloadKey?: string;
+    payloadValue?: string;
+    payloadContains?: string;
+}
+interface GraphEdgeQuery {
+    src?: string;
+    dst?: string;
+    relation?: GraphRelation;
+    relations?: GraphRelation[];
+}
+type GraphTraverseDirection = 'out' | 'in' | 'both';
+interface GraphTraverseQuery {
+    from: string | string[];
+    relations?: GraphRelation[];
+    direction?: GraphTraverseDirection;
+    depth?: number;
+}
+interface GraphSubgraph {
+    nodes: GraphNode[];
+    edges: GraphEdge[];
+}
+interface GraphRouteContext {
+    snapshotId: string;
+    sourceHash: string;
+    routeNode: GraphNode;
+    ranking: {
+        method: 'weighted_traversal' | 'weighted_traversal_with_task_boost';
+        seed: string;
+        task_keywords: string[];
+    };
+    summary: {
+        nodes: number;
+        edges: number;
+        pages: number;
+        shells: number;
+        patterns: number;
+        components: number;
+        tokens: number;
+        localRules: number;
+        styleBridge: number;
+        openFindings: number;
+        evidence: number;
+        sourceArtifacts: number;
+    };
+    ids: {
+        pages: string[];
+        shells: string[];
+        patterns: string[];
+        components: string[];
+        tokens: string[];
+        localRules: string[];
+        styleBridge: string[];
+        openFindings: string[];
+        evidence: string[];
+        sourceArtifacts: string[];
+    };
+    ranked: Array<{
+        id: string;
+        type: GraphNodeType;
+        score: number;
+        reason: string;
+        matched_terms?: string[];
+    }>;
+    nodes: GraphNode[];
+    edges: GraphEdge[];
+}
+interface BuildGraphRouteContextOptions {
+    task?: string;
+}
+interface GraphImpactContext {
+    snapshotId: string;
+    sourceHash: string;
+    seedNodes: GraphNode[];
+    missingNodeIds: string[];
+    ranking: {
+        method: 'impact_traversal' | 'impact_traversal_with_task_boost';
+        seed: string[];
+        task_keywords: string[];
+    };
+    summary: {
+        nodes: number;
+        edges: number;
+        totalNodes: number;
+        totalEdges: number;
+        truncated: boolean;
+        routes: number;
+        pages: number;
+        shells: number;
+        patterns: number;
+        components: number;
+        tokens: number;
+        localRules: number;
+        styleBridge: number;
+        openFindings: number;
+        evidence: number;
+        repairs: number;
+        sourceArtifacts: number;
+    };
+    ids: {
+        routes: string[];
+        pages: string[];
+        shells: string[];
+        patterns: string[];
+        components: string[];
+        tokens: string[];
+        localRules: string[];
+        styleBridge: string[];
+        openFindings: string[];
+        evidence: string[];
+        repairs: string[];
+        sourceArtifacts: string[];
+    };
+    ranked: Array<{
+        id: string;
+        type: GraphNodeType;
+        score: number;
+        reason: string;
+        matched_terms?: string[];
+    }>;
+    nodes: GraphNode[];
+    edges: GraphEdge[];
+}
+interface BuildGraphImpactContextOptions {
+    task?: string;
+    limit?: number;
+}
+interface GraphStore {
+    open(projectRoot: string): Promise<void>;
+    close(): Promise<void>;
+    upsertNode(node: GraphNode): Promise<void>;
+    upsertEdge(edge: GraphEdge): Promise<void>;
+    getNode(id: string): Promise<GraphNode | null>;
+    queryNodes(query: GraphNodeQuery): Promise<GraphNode[]>;
+    queryEdges(query: GraphEdgeQuery): Promise<GraphEdge[]>;
+    traverse(query: GraphTraverseQuery): Promise<GraphSubgraph>;
+    writeSnapshot(snapshot: GraphSnapshot): Promise<void>;
+    readSnapshot(id?: string): Promise<GraphSnapshot | null>;
+}
+interface MemoryGraphStoreSeed {
+    nodes?: GraphNode[];
+    edges?: GraphEdge[];
+    snapshots?: GraphSnapshot[];
+}
+interface BuildGraphSnapshotFromIROptions {
+    projectId?: string;
+    snapshotId?: string;
+    createdAt?: string;
+    parentId?: string;
+    sourceHash?: string;
+    git?: GraphSnapshot['git'];
+    sourceArtifact?: SourceArtifact;
+}
+type BuildGraphSnapshotFromEssenceOptions = BuildGraphSnapshotFromIROptions;
+declare function sortGraphNodes(nodes: GraphNode[]): GraphNode[];
+declare function sortGraphEdges(edges: GraphEdge[]): GraphEdge[];
+declare function normalizeGraphSnapshot(snapshot: GraphSnapshot): GraphSnapshot;
+declare function diffGraphSnapshots(from: GraphSnapshot | null, to: GraphSnapshot): GraphDiff;
+declare function summarizeGraphDiff(diff: GraphDiff | null | undefined): GraphDiffSummary;
+declare function graphPayloadRecord(payload: unknown): Record<string, unknown>;
+declare function graphPayloadString(payload: unknown, key: string): string | undefined;
+declare function graphContractHash(snapshot: GraphSnapshot): string;
+declare function buildContractCapsuleFromSnapshot(snapshot: GraphSnapshot, options?: BuildContractCapsuleOptions): ContractCapsule;
+declare function buildGraphRouteContext(snapshot: GraphSnapshot | null | undefined, route: string, options?: BuildGraphRouteContextOptions): GraphRouteContext | null;
+declare function buildGraphImpactContext(snapshot: GraphSnapshot | null | undefined, seed: string | string[], options?: BuildGraphImpactContextOptions): GraphImpactContext | null;
+declare function buildGraphSnapshotFromEssence(essence: EssenceV4, options?: BuildGraphSnapshotFromEssenceOptions): GraphSnapshot;
+declare function buildGraphSnapshotFromIR(ir: IRAppNode, options?: BuildGraphSnapshotFromIROptions): GraphSnapshot;
+declare function createMemoryGraphStore(seed?: MemoryGraphStoreSeed): GraphStore;
+
 interface ResolvedPatternEntry {
     pattern: Pattern;
     preset: ResolvedPreset;
@@ -657,4 +1020,4 @@ declare function resolveEssence(essence: EssenceFile, resolver: ContentResolver)
 /** Convert a kebab-case or snake_case string to PascalCase */
 declare function pascalCase(str: string): string;
 
-export { type CompileExecutionPackBundleOptions, EXECUTION_PACK_BUNDLE_SCHEMA_URL, EXECUTION_PACK_SCHEMA_URLS, type ExecutionPackAntiPattern, type ExecutionPackBase, type ExecutionPackBundle, type ExecutionPackExample, type ExecutionPackManifest, type ExecutionPackScope, type ExecutionPackSelector, type ExecutionPackSuccessCheck, type ExecutionPackTarget, type ExecutionPackTokenBudget, type ExecutionPackType, type IRAppNode, type IRBreakpointEntry, type IRCardWrapping, type IRGridNode, type IRHookType, type IRLayer, type IRNavItem, type IRNode, type IRNodeType, type IRPageNode, type IRPatternMeta, type IRPatternNode, type IRRoute, type IRShellConfig, type IRShellNode, type IRSpatial, type IRStoreNode, type IRTheme, type IRThemeDecoration, type IRVisualEffect, type IRWiring, type IRWiringSignal, type MutationExecutionPack, type MutationPackBuilderOptions, type MutationPackData, type MutationPackKind, PACK_MANIFEST_SCHEMA_URL, type PackManifestEntry, type PackManifestMutationEntry, type PackManifestPageEntry, type PackManifestSectionEntry, type PageExecutionPack, type PagePackBuilderOptions, type PagePackData, type PagePackInput, type PagePackPattern, type PipelineOptions, type PipelineResult, type RealizationAdapter, type RealizationInteractionPlaceholder, type RealizationMockDataSeed, type RealizationPlan, type RealizationRoute, type ResolvedEssence, type ResolvedPage, type ReviewExecutionPack, type ReviewPackBuilderOptions, type ReviewPackData, type ReviewPackKind, SELECTED_EXECUTION_PACK_SCHEMA_URL, type ScaffoldExecutionPack, type ScaffoldPackBuilderOptions, type ScaffoldPackData, type ScaffoldPackRoute, type SectionExecutionPack, type SectionPackBuilderOptions, type SectionPackData, type SectionPackInput, type SectionPackRoute, type SelectedExecutionPack, type SelectedExecutionPackResponse, buildMutationPack, buildPageIR, buildPagePack, buildReviewPack, buildScaffoldPack, buildSectionPack, compileExecutionPackBundle, compileRealizationPlan, compileSelectedExecutionPack, countPatterns, findNodes, listPackPages, listPackSections, pascalCase, renderExecutionPackMarkdown, resolveEssence, resolvePackAdapter, resolveVisualEffects, runPipeline, selectExecutionPackFromBundle, validateIR, walkIR };
+export { type BuildContractCapsuleOptions, type BuildGraphImpactContextOptions, type BuildGraphRouteContextOptions, type BuildGraphSnapshotFromEssenceOptions, type BuildGraphSnapshotFromIROptions, CONTRACT_CAPSULE_SCHEMA_URL, type CompileExecutionPackBundleOptions, type ContractCapsule, type ContractCapsuleFinding, type ContractCapsuleRoute, type ContractCapsuleSourceArtifact, type ContractCapsuleVocabularyItem, DEFAULT_CONTRACT_CAPSULE_SOURCE_ARTIFACT_LIMIT, EXECUTION_PACK_BUNDLE_SCHEMA_URL, EXECUTION_PACK_SCHEMA_URLS, type ExecutionPackAntiPattern, type ExecutionPackBase, type ExecutionPackBundle, type ExecutionPackExample, type ExecutionPackManifest, type ExecutionPackScope, type ExecutionPackSelector, type ExecutionPackSuccessCheck, type ExecutionPackTarget, type ExecutionPackTokenBudget, type ExecutionPackType, GRAPH_COMMON_SCHEMA_URL, GRAPH_DIFF_SCHEMA_URL, GRAPH_MANIFEST_SCHEMA_URL, GRAPH_NODE_TYPES, GRAPH_RELATIONS, GRAPH_SCHEMA_VERSION, GRAPH_SNAPSHOT_SCHEMA_URL, type GraphDiff, type GraphDiffOp, type GraphDiffOpType, type GraphDiffSummary, type GraphEdge, type GraphEdgeQuery, type GraphFinding, type GraphImpactContext, type GraphManifest, type GraphNode, type GraphNodeQuery, type GraphNodeType, type GraphRelation, type GraphRouteContext, type GraphSnapshot, type GraphStore, type GraphSubgraph, type GraphTraverseDirection, type GraphTraverseQuery, type IRAppNode, type IRBreakpointEntry, type IRCardWrapping, type IRGridNode, type IRHookType, type IRLayer, type IRNavItem, type IRNode, type IRNodeType, type IRPageNode, type IRPatternMeta, type IRPatternNode, type IRRoute, type IRShellConfig, type IRShellNode, type IRSpatial, type IRStoreNode, type IRTheme, type IRThemeDecoration, type IRVisualEffect, type IRWiring, type IRWiringSignal, type MemoryGraphStoreSeed, type MutationExecutionPack, type MutationPackBuilderOptions, type MutationPackData, type MutationPackKind, PACK_MANIFEST_SCHEMA_URL, type PackManifestEntry, type PackManifestMutationEntry, type PackManifestPageEntry, type PackManifestSectionEntry, type PageExecutionPack, type PagePackBuilderOptions, type PagePackData, type PagePackInput, type PagePackPattern, type PipelineOptions, type PipelineResult, type RealizationAdapter, type RealizationInteractionPlaceholder, type RealizationMockDataSeed, type RealizationPlan, type RealizationRoute, type ResolvedEssence, type ResolvedPage, type ReviewExecutionPack, type ReviewPackBuilderOptions, type ReviewPackData, type ReviewPackKind, SELECTED_EXECUTION_PACK_SCHEMA_URL, type ScaffoldExecutionPack, type ScaffoldPackBuilderOptions, type ScaffoldPackData, type ScaffoldPackRoute, type SectionExecutionPack, type SectionPackBuilderOptions, type SectionPackData, type SectionPackInput, type SectionPackRoute, type SelectedExecutionPack, type SelectedExecutionPackResponse, type SourceArtifact, buildContractCapsuleFromSnapshot, buildGraphImpactContext, buildGraphRouteContext, buildGraphSnapshotFromEssence, buildGraphSnapshotFromIR, buildMutationPack, buildPageIR, buildPagePack, buildReviewPack, buildScaffoldPack, buildSectionPack, compileExecutionPackBundle, compileRealizationPlan, compileSelectedExecutionPack, countPatterns, createMemoryGraphStore, diffGraphSnapshots, findNodes, graphContractHash, graphPayloadRecord, graphPayloadString, listPackPages, listPackSections, normalizeGraphSnapshot, pascalCase, renderExecutionPackMarkdown, resolveEssence, resolvePackAdapter, resolveVisualEffects, runPipeline, selectExecutionPackFromBundle, sortGraphEdges, sortGraphNodes, summarizeGraphDiff, validateIR, walkIR };