Release v0.34.0 adds capability-operation schema v4, FastMCP client support, and Firebase detection. Read release notes
Unoplat Code Confluence
ContributionDeterministic Interface Discovery Schema (DIDS)

Deterministic Interface Discovery Schema (DIDS)

Define framework and library patterns for detection of app interfaces in Unoplat Code Confluence.

The Deterministic Interface Discovery Schema (DIDS) gives contributors a deterministic structured way to define how Unoplat Code Confluence should identify and analyze framework and library patterns in codebases across programming languages.

Quick Reference

Source of Truth

Background and Problem Statement

Background

Modern code intelligence systems usually cannot read entire repositories for every request. In large codebases, they typically rely on a retrieval pipeline:

  1. Chunk source files into indexable units
  2. Compute embeddings for semantic lookup
  3. Retrieve nearest candidates from the index
  4. Rerank candidates for relevance
  5. Assemble final context for analysis or generation

This pattern works well for broad navigation and question answering, but it is fundamentally probabilistic. Retrieval quality depends on chunking boundaries, embedding behavior, reranking heuristics, and prompt phrasing.

At scale, this pipeline is also expensive to execute and maintain: indexing/embedding jobs must be recomputed, vector infrastructure must be operated, and retrieval quality must be continuously tuned. The approach is also non-extensible for deterministic interface discovery because framework-specific logic is usually implemented as ad-hoc runtime behavior instead of a reusable contract.

For interface discovery, we need stronger guarantees than "likely relevant context." We need reproducible detection of framework and library constructs so downstream systems can build stable blueprints, generate reliable structured output, and reason across repositories consistently.

The Deterministic Interface Discovery Schema (DIDS) introduces that missing contract: a versioned, machine-enforceable way to describe what to detect and how those detections should be interpreted.

Problem Statement

For any coding task, an agent or human needs a reliable blueprint of the codebase. Today, that blueprint is inferred mostly from semantic retrieval and ad-hoc heuristics, which creates following problems:

  1. Non-determinism: the same repository can produce different detections across runs.
  2. High execution and maintenance cost: embeddings, indexes, and tuning loops create ongoing operational overhead.
  3. Low extensibility: adding support for new frameworks or internal patterns requires custom, scattered logic.
  4. Weak verifiability: behavior is hard to validate in CI because rules are implicit instead of contract-driven.
  5. Lack of open standards: without an open, versioned schema, definitions are harder to share, interoperate, and evolve safely.

We therefore need a deterministic, schema-first standard that defines framework and library capabilities and operations with explicit constraints and validation rules, enabling consistent interface discovery across any tech ecosystem.

Goals

This specification work aims to:

  1. Define a machine-enforceable detection contract for framework and library capabilities based on programming constructs like annotations, calls, inheritance, and imports.
  2. Improve contributor correctness with explicit constraints and validation expectations
  3. Support safe schema evolution with clear compatibility and migration expectations

Schema Structure

Top Level Structure

The schema organizes definitions hierarchically by language and library:

{
  "python": {
    "fastapi": { /* library definition */ },
    "django": { /* library definition */ }
  },
  "javascript": {
    "express": { /* library definition */ },
    "react": { /* library definition */ }
  }
}

Supported Languages

Prop

Type

Frameworks Supported

Browse the Supported Frameworks catalog to see currently available libraries by programming language.

Library Definition Structure

Each library definition describes a framework or library that Unoplat Code Confluence should recognize.

Required Fields

Prop

Type

Optional Fields

Prop

Type

Capability And Operation Hierarchy

Two Simple Questions

  • Capability = the role this code plays in the system, such as rest_api, authentication, or file_storage
  • Operation = the action performed by that role, such as defining a route, checking a user, or uploading a file

Capability Definition Structure

Each capability groups related operations under a library-agnostic architectural family.

Prop

Type

Capability Enum Validation

Capability keys are not free-form labels. They are validated against the published capability enum, which means contributors must use an existing architectural capability identifier from the schema.

If you need a new capability family, do not introduce an ad-hoc key in a framework definition. Update the schema and validation layer first, then use that enum value in your contributed definition.

Published Capability Enum

The following capability families are taken from custom-framework-lib-schema-v4.json. Only these values are accepted as capability keys.

Operation Definition Structure

Each operation is the precise detection contract that tree-sitter and downstream validation use. Operation keys are contributor-chosen identifiers validated by object shape, not a global enum.

Required Fields

Prop

Type

Optional Fields

Prop

Type

target_level Values

Prop

Type

concept Values

Prop

Type

Concept Examples

  • AnnotationLike: @app.get("/"), @Component, [HttpGet], @dataclass
  • CallExpression: mapped_column(), Field(), relationship(), useState()
  • Inheritance: class User(BaseModel), class MyView(APIView), class App extends Component
  • FunctionDefinition: export async function GET(request: Request) { ... }

Grouping Rules

Group At The Right Layer

  • Put multiple operations under one capability when they belong to the same architectural workflow, such as rest_api -> get, post, put, and delete
  • Put multiple absolute paths inside one operation only when they share the same detection meaning, target_level, concept, construct_query, confidence semantics, and notes
  • If a variant changes the semantics that matter downstream, keep it as a separate operation instead of collapsing paths into one broad regex

Detection Heuristics

Detection is import-gated and regex-refined. absolute_paths must be present in the file imports, and construct_query refines the tree-sitter patterns used to match decorators, calls, inheritance, and exported function declarations.

Low-Confidence Guidance

If an operation uses base_confidence < 0.70, include disambiguation instructions in notes so downstream validation can reliably confirm or reject ambiguous matches.

construct_query Properties

Context-Dependent

Available properties depend on the operation's concept value. Use the appropriate regex for your operation type.

Prop

Type

Real Framework Examples

FastAPI Example

This example shows HTTP verb operations directly under the rest_api capability. Each verb is its own operation with the detection contract defined inline.

{
  "python": {
    "fastapi": {
      "docs_url": "https://fastapi.tiangolo.com",
      "description": "Modern, fast web framework for building APIs with Python",
      "capabilities": {
        "rest_api": {
          "description": "HTTP verb decorators that register route handlers on FastAPI or APIRouter instances.",
          "operations": {
            "get": {
              "description": "FastAPI GET route handler.",
              "absolute_paths": [
                "fastapi.FastAPI",
                "fastapi.applications.FastAPI",
                "fastapi.APIRouter",
                "fastapi.routing.APIRouter"
              ],
              "target_level": "function",
              "concept": "AnnotationLike",
              "construct_query": {
                "method_regex": "^get$"
              },
              "startpoint": true
            },
            "post": {
              "description": "FastAPI POST route handler.",
              "absolute_paths": [
                "fastapi.FastAPI",
                "fastapi.applications.FastAPI",
                "fastapi.APIRouter",
                "fastapi.routing.APIRouter"
              ],
              "target_level": "function",
              "concept": "AnnotationLike",
              "construct_query": {
                "method_regex": "^post$"
              },
              "startpoint": true
            }
          }
        },
        "background_worker": {
          "description": "Background task execution using FastAPI BackgroundTasks.",
          "operations": {
            "background_tasks": {
              "description": "Background task execution using BackgroundTasks.",
              "absolute_paths": [
                "fastapi.BackgroundTasks"
              ],
              "target_level": "function",
              "concept": "CallExpression",
              "base_confidence": 0.88
            }
          }
        }
      }
    }
  }
}

SQLAlchemy Example

This example shows a Python relational database library with an Inheritance-based model operation.

{
  "python": {
    "sqlalchemy": {
      "docs_url": "https://docs.sqlalchemy.org",
      "description": "Python ORM and SQL toolkit for relational database access",
      "capabilities": {
        "relational_database": {
          "description": "SQLAlchemy ORM declarative model definitions.",
          "operations": {
            "db_data_model": {
              "description": "Base class for SQLAlchemy declarative models.",
              "absolute_paths": [
                "sqlalchemy.ext.declarative.declarative_base",
                "sqlalchemy.orm.declarative_base"
              ],
              "target_level": "class",
              "concept": "Inheritance"
            }
          }
        }
      }
    }
  }
}

Firebase TypeScript SDK Example (compact)

This compact example shows the same operation-level model used by ingestion for Firebase.
For the full maintained definition, see framework-definitions/typescript/firebase.json in ingestion.

Vetted Firebase Capability → Operation Map

  • authentication: sign_in, create_user, sign_out, observe_state
  • document_database: create, read, update, delete, query, listen
  • object_storage: upload, download, delete
  • telemetry: log_event, set_user, set_user_properties
  • rpc_server: call
  • rest_api: request
  • rpc_client: invoke
  • http_client: request
  • scheduler: schedule
  • change_data_capture: create, update, delete, write
  • job_queue: dispatch
{
  "typescript": {
    "firebase": {
      "docs_url": "https://firebase.google.com/docs/reference/js",
      "description": "Firebase TypeScript SDK capabilities across auth, data, storage, telemetry, and Cloud Functions client/server patterns.",
      "capabilities": {
        "authentication": {
          "description": "Firebase Authentication sign-in and session state flows.",
          "operations": {
            "sign_in": {
              "description": "Signs users in through Firebase Authentication provider/credential flows.",
              "absolute_paths": [
                "firebase/auth.signInWithEmailAndPassword",
                "firebase/auth.signInWithPopup"
              ],
              "target_level": "function",
              "concept": "CallExpression",
              "base_confidence": 0.93
            }
          }
        },
        "document_database": {
          "description": "Cloud Firestore document CRUD/query/listen patterns.",
          "operations": {
            "query": {
              "description": "Builds constrained Firestore queries.",
              "absolute_paths": [
                "firebase/firestore.query",
                "firebase/firestore.where",
                "firebase/firestore.orderBy"
              ],
              "target_level": "function",
              "concept": "CallExpression",
              "base_confidence": 0.86
            },
            "listen": {
              "description": "Subscribes to real-time Firestore updates.",
              "absolute_paths": [
                "firebase/firestore.onSnapshot"
              ],
              "target_level": "function",
              "concept": "CallExpression",
              "base_confidence": 0.92
            }
          }
        },
        "rpc_server": {
          "description": "Cloud Functions callable RPC handlers.",
          "operations": {
            "call": {
              "description": "Defines callable Cloud Functions handlers.",
              "absolute_paths": [
                "firebase-functions/v2/https.onCall"
              ],
              "target_level": "function",
              "concept": "CallExpression",
              "base_confidence": 0.95,
              "startpoint": true
            }
          }
        },
        "rest_api": {
          "description": "Cloud Functions HTTP request handlers.",
          "operations": {
            "request": {
              "description": "Defines HTTP request handlers via Cloud Functions.",
              "absolute_paths": [
                "firebase-functions/v2/https.onRequest"
              ],
              "target_level": "function",
              "concept": "CallExpression",
              "base_confidence": 0.95,
              "startpoint": true
            }
          }
        },
        "rpc_client": {
          "description": "Callable function invocation from Firebase client SDK.",
          "operations": {
            "invoke": {
              "description": "Invokes callable Cloud Functions by name.",
              "absolute_paths": [
                "firebase/functions.httpsCallable"
              ],
              "target_level": "function",
              "concept": "CallExpression",
              "base_confidence": 0.9
            }
          }
        },
        "change_data_capture": {
          "description": "Cloud Functions Firestore event triggers.",
          "operations": {
            "write": {
              "description": "Handles Firestore document write events.",
              "absolute_paths": [
                "firebase-functions/v2/firestore.onDocumentWritten"
              ],
              "target_level": "function",
              "concept": "CallExpression",
              "base_confidence": 0.95,
              "startpoint": true
            }
          }
        }
      }
    }
  }
}

Validation Rules

Mandatory Constraints

The schema enforces these mandatory constraints:

  • Capability keys must match the published capability enum (for example rest_api, authentication, relational_database)
  • Capability validation happens on the capability key itself, so unsupported names such as firebase_auth or route_get will fail schema validation even if the nested operation shape is valid
  • Operation keys are contributor-chosen identifiers validated by object shape, not a global enum
  • Every operation must define description, absolute_paths, target_level, and concept
  • CallExpression operations must use target_level: "function" and define base_confidence
  • Low-confidence CallExpression operations with base_confidence < 0.70 must include non-empty notes
  • Inheritance operations must use target_level: "class"
  • FunctionDefinition operations must use target_level: "function"
  • base_confidence is only allowed on CallExpression operations; the schema rejects it on other concepts

Violations will cause schema validation to fail.

Pattern Validation

Prop

Type

Contributing Schema Updates

Coming Soon

Detailed contribution guidelines including step-by-step instructions, validation commands, and testing workflows will be added here.

Future Enhancements

Coming Soon

Details on planned schema extensions — additional programming languages, capability-specific operation profiles, and richer qualifier metadata — will be documented here.

Setup

Development environment setup for Unoplat Code Confluence

On this page

Background and Problem StatementBackgroundProblem StatementGoalsSchema StructureTop Level StructureSupported LanguagesFrameworks SupportedLibrary Definition StructureRequired FieldsOptional FieldsCapability And Operation HierarchyCapability Definition StructureCapability Enum ValidationPublished Capability EnumOperation Definition StructureRequired FieldsOptional Fieldstarget_level Valuesconcept ValuesGrouping RulesDetection Heuristicsconstruct_query PropertiesReal Framework ExamplesFastAPI ExampleSQLAlchemy ExampleFirebase TypeScript SDK Example (compact)Validation RulesPattern ValidationContributing Schema UpdatesFuture Enhancements