markitect-tool/src/markitect_tool/extension/builtins.py

"""Built-in internal extension descriptors."""

from __future__ import annotations

from markitect_tool.extension.registry import ExtensionDescriptor, ExtensionRegistry
from markitect_tool.extension.processing import ProcessingCapability
from markitect_tool.query import default_query_engine_registry


def builtin_extension_registry() -> ExtensionRegistry:
    """Return descriptors for built-in Markitect extensions."""

    registry = default_query_engine_registry().extension_registry()
    for descriptor in _processor_descriptors() + [
        _local_sqlite_backend_descriptor(),
        _workflow_engine_descriptor(),
        _runtime_context_descriptor(),
        _runtime_form_state_descriptor(),
        _runtime_assessment_descriptor(),
        _local_label_policy_descriptor(),
    ]:
        registry.register(descriptor)
    return registry


def _processor_descriptors() -> list[ExtensionDescriptor]:
    return [
        ExtensionDescriptor(
            id="processor.identity",
            kind="processor",
            summary="Return fenced block content unchanged.",
            capabilities=[
                ProcessingCapability(id="processor", kind="execute"),
                ProcessingCapability(id="deterministic", kind="execution"),
            ],
            input_contract="ProcessorRequest",
            output_contract="ProcessorResult",
            diagnostics_namespace="processor",
            provenance_prefix="processor.identity",
            cli={"commands": ["mkt process"]},
            docs=["docs/processors.md"],
        ),
        ExtensionDescriptor(
            id="processor.uppercase",
            kind="processor",
            summary="Uppercase fenced block content deterministically.",
            capabilities=[
                ProcessingCapability(id="processor", kind="execute"),
                ProcessingCapability(id="deterministic", kind="execution"),
            ],
            input_contract="ProcessorRequest",
            output_contract="ProcessorResult",
            diagnostics_namespace="processor",
            provenance_prefix="processor.uppercase",
            cli={"commands": ["mkt process"]},
            docs=["docs/processors.md"],
        ),
        ExtensionDescriptor(
            id="processor.include",
            kind="processor",
            summary="Resolve a content reference into fenced block output.",
            capabilities=[
                ProcessingCapability(id="processor", kind="execute"),
                ProcessingCapability(id="references", kind="read"),
                ProcessingCapability(id="filesystem", kind="read"),
            ],
            safety={"reads_files": True, "writes_files": False, "network": False},
            input_contract="ProcessorRequest",
            output_contract="ProcessorResult",
            diagnostics_namespace="processor",
            provenance_prefix="processor.include",
            cli={"commands": ["mkt process"]},
            docs=["docs/processors.md", "docs/content-references.md"],
        ),
    ]


def _local_sqlite_backend_descriptor() -> ExtensionDescriptor:
    return ExtensionDescriptor(
        id="backend.local-sqlite",
        kind="backend",
        summary="Local SQLite snapshot, metadata, JSON, and FTS5 index backend.",
        capabilities=[
            ProcessingCapability(id="snapshots", kind="backend"),
            ProcessingCapability(id="ast", kind="backend"),
            ProcessingCapability(id="json", kind="backend"),
            ProcessingCapability(id="fts", kind="backend"),
            ProcessingCapability(id="sql", kind="backend"),
            ProcessingCapability(id="provenance", kind="backend"),
            ProcessingCapability(id="policy_filter", kind="backend"),
        ],
        safety={"reads_files": True, "writes_local_cache": True, "network": False},
        input_contract="Markdown files/directories",
        output_contract="SQLite snapshot/index store",
        diagnostics_namespace="backend.local_sqlite",
        provenance_prefix="local_snapshot_store",
        cli={"commands": ["mkt cache init", "mkt cache index", "mkt cache query", "mkt search"]},
        docs=["docs/local-index-backend.md", "docs/backend-fabric.md"],
        examples=["examples/backends/local-sqlite-backend.md"],
    )


def _workflow_engine_descriptor() -> ExtensionDescriptor:
    return ExtensionDescriptor(
        id="workflow.markdown-dataflow",
        kind="workflow-engine",
        summary="Declarative Markdown dataflow workflow engine.",
        capabilities=[
            ProcessingCapability(id="workflow", kind="execute"),
            ProcessingCapability(id="markdown", kind="read"),
            ProcessingCapability(id="templates", kind="execute"),
            ProcessingCapability(id="provenance", kind="emit"),
        ],
        safety={
            "reads_files": True,
            "writes_output_files": True,
            "network": False,
            "assisted_generation": "adapter-only",
        },
        input_contract="Markdown/YAML workflow definition",
        output_contract="WorkflowRunResult",
        diagnostics_namespace="workflow",
        provenance_prefix="workflow",
        cli={"commands": ["mkt workflow inspect", "mkt workflow plan", "mkt workflow run"]},
        docs=["docs/workflow-definition-standard.md"],
        examples=["examples/workflows/adr-release-notes.workflow.md"],
    )


def _runtime_context_descriptor() -> ExtensionDescriptor:
    return ExtensionDescriptor(
        id="runtime.context",
        kind="runtime",
        summary="YAML/JSON runtime context loader for document contracts.",
        capabilities=[
            ProcessingCapability(id="context", kind="read"),
            ProcessingCapability(id="json-schema", kind="validate"),
            ProcessingCapability(id="diagnostics", kind="emit"),
        ],
        safety={"reads_files": True, "network": False},
        input_contract="YAML/JSON runtime context file",
        output_contract="RuntimeContext",
        diagnostics_namespace="runtime.context",
        provenance_prefix="runtime.context",
        cli={"commands": ["mkt contract check --context", "mkt contract form-state"]},
        docs=["docs/runtime-context-forms-assessments.md"],
        examples=["examples/runtime/business-letter.context.yaml"],
    )


def _runtime_form_state_descriptor() -> ExtensionDescriptor:
    return ExtensionDescriptor(
        id="runtime.form-state",
        kind="runtime",
        summary="UI-neutral field prefill, validation, and dynamic rule engine.",
        capabilities=[
            ProcessingCapability(id="forms", kind="evaluate"),
            ProcessingCapability(id="rules", kind="evaluate"),
            ProcessingCapability(id="contracts", kind="validate"),
            ProcessingCapability(id="diagnostics", kind="emit"),
        ],
        safety={"reads_files": False, "network": False},
        input_contract="Document + DocumentContract + RuntimeContext",
        output_contract="FormState",
        diagnostics_namespace="runtime",
        provenance_prefix="runtime.form_state",
        cli={"commands": ["mkt contract form-state"]},
        docs=["docs/runtime-context-forms-assessments.md"],
        examples=["examples/runtime/workplan-dynamic.contract.md"],
    )


def _runtime_assessment_descriptor() -> ExtensionDescriptor:
    return ExtensionDescriptor(
        id="runtime.assessment",
        kind="assessment-runner",
        summary="Provider-neutral rubric assessment request, result, and cache boundary.",
        capabilities=[
            ProcessingCapability(id="assessment", kind="execute"),
            ProcessingCapability(id="rubrics", kind="read"),
            ProcessingCapability(id="cache-key", kind="compute"),
            ProcessingCapability(id="diagnostics", kind="emit"),
        ],
        safety={"network": "adapter-only", "provider_calls": "adapter-only"},
        input_contract="AssessmentRequest",
        output_contract="AssessmentResult",
        diagnostics_namespace="runtime.assessment",
        provenance_prefix="runtime.assessment",
        docs=["docs/runtime-context-forms-assessments.md"],
        examples=["examples/runtime/concept-note-assessment.contract.md"],
        metadata={"provider_implementation": "external adapter required"},
    )


def _local_label_policy_descriptor() -> ExtensionDescriptor:
    return ExtensionDescriptor(
        id="policy.local-label",
        kind="policy-gateway",
        summary="Local label, trust-zone, and path policy gateway.",
        capabilities=[
            ProcessingCapability(id="policy", kind="authorize"),
            ProcessingCapability(id="policy_filter", kind="filter"),
            ProcessingCapability(id="diagnostics", kind="emit"),
            ProcessingCapability(id="provenance", kind="emit"),
        ],
        safety={"network": False, "external_policy_engine": False},
        input_contract="PolicySubject + PolicyObject + local label policy",
        output_contract="PolicyDecision | PolicyFilterResult",
        diagnostics_namespace="policy",
        provenance_prefix="policy.local_label",
        cli={
            "commands": [
                "mkt policy check",
                "mkt cache query --policy",
                "mkt search --policy",
            ]
        },
        docs=["docs/access-control-policy-gateway.md"],
        examples=["examples/policy/local-label-policy.yaml"],
        metadata={
            "external_adapters": [
                "RelationshipPolicyAdapter",
                "RulePolicyAdapter",
            ]
        },
    )