compos-cli 0.0.0__py3-none-any.whl

compos/core/write_pipeline.py

@@ -0,0 +1,574 @@
+"""Write validation pipeline — ALL map mutations go through here.
+
+Six-stage pipeline:
+1. Schema validation (enforced by Pydantic at construction)
+2. Provenance completeness (enforced by schema validators)
+3. ID uniqueness (register only)
+4. Referential integrity
+5. Structural safety (cycle detection for relationships)
+6. Merge engine (update only)
+
+The pipeline is pure — it returns a WriteResult with the new map.
+It does NOT persist. The caller is responsible for storage I/O.
+
+Removal is provenance-gated: a caller can only remove objects created
+by the same or lower priority source. Lower-priority callers get a
+rejection with a warning flagging the object for human review.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from datetime import UTC, datetime
+from enum import StrEnum
+from typing import Any
+
+from compos.core.graph import evaluate_proposed_change
+from compos.core.integrity import (
+    check_id_uniqueness,
+    check_referential_integrity,
+    check_remove_blocked,
+)
+from compos.core.merge import merge_object
+from compos.core.merge_log import MergeLogEntry, create_entry
+from compos.core.versioning import VersionBump, increment_version
+from compos.schema.models import (
+    Component,
+    ComposMap,
+    Constraint,
+    ConstraintStatus,
+    Decision,
+    DecisionStatus,
+    ObjectStatus,
+    ProvenanceSource,
+    Relationship,
+    Risk,
+    RiskStatus,
+)
+
+# ---------------------------------------------------------------------------
+# Types
+# ---------------------------------------------------------------------------
+
+type MapObject = Component | Relationship | Constraint | Risk | Decision
+
+
+class OperationType(StrEnum):
+    REGISTER = "register"
+    UPDATE = "update"
+    REMOVE = "remove"
+
+
+@dataclass(frozen=True, slots=True)
+class WriteError:
+    """A single validation failure."""
+
+    stage: str
+    message: str
+    details: Any = None
+
+
+@dataclass(frozen=True, slots=True)
+class WriteResult:
+    """Outcome of a write pipeline execution."""
+
+    success: bool
+    new_map: ComposMap | None
+    new_version: int | None
+    merge_summary: MergeLogEntry | None
+    errors: tuple[WriteError, ...]
+    warnings: tuple[str, ...]
+
+
+# ---------------------------------------------------------------------------
+# Collection name mapping
+# ---------------------------------------------------------------------------
+
+_TYPE_TO_COLLECTION: dict[type, str] = {
+    Component: "components",
+    Relationship: "relationships",
+    Constraint: "constraints",
+    Risk: "risks",
+    Decision: "decisions",
+}
+
+_TYPE_TO_NAME: dict[type, str] = {
+    Component: "component",
+    Relationship: "relationship",
+    Constraint: "constraint",
+    Risk: "risk",
+    Decision: "decision",
+}
+
+# Type-aware removal: each type maps to its correct REMOVED status value
+_TYPE_TO_REMOVED_STATUS: dict[
+    type, ObjectStatus | ConstraintStatus | RiskStatus | DecisionStatus
+] = {
+    Component: ObjectStatus.REMOVED,
+    Relationship: ObjectStatus.REMOVED,
+    Constraint: ConstraintStatus.REMOVED,
+    Risk: RiskStatus.REMOVED,
+    Decision: DecisionStatus.REMOVED,
+}
+
+# Provenance priority for gating removal
+_SOURCE_PRIORITY: dict[ProvenanceSource, int] = {
+    ProvenanceSource.STATIC_ANALYSIS: 1,
+    ProvenanceSource.AI_ANNOTATED: 2,
+    ProvenanceSource.HUMAN_INPUT: 3,
+}
+
+
+# ---------------------------------------------------------------------------
+# Internal helpers
+# ---------------------------------------------------------------------------
+
+
+def _fail(stage: str, message: str, details: Any = None) -> WriteResult:
+    """Shorthand for a failed WriteResult."""
+    return WriteResult(
+        success=False,
+        new_map=None,
+        new_version=None,
+        merge_summary=None,
+        errors=(WriteError(stage=stage, message=message, details=details),),
+        warnings=(),
+    )
+
+
+def _find_existing(
+    compos_map: ComposMap, obj_id: str, obj_type: type,
+) -> MapObject | None:
+    """Find an existing object by ID in its collection."""
+    collection = _TYPE_TO_COLLECTION[obj_type]
+    for item in getattr(compos_map, collection):
+        if item.id == obj_id:
+            return item  # type: ignore[no-any-return]
+    return None
+
+
+def _build_map_with(
+    compos_map: ComposMap,
+    collection: str,
+    new_items: tuple[Any, ...],
+) -> ComposMap:
+    """Return a new ComposMap with one collection replaced."""
+    data = compos_map.model_dump(by_alias=False)
+    data[collection] = new_items
+    return ComposMap.model_validate(data)
+
+
+def _replace_in_collection(
+    compos_map: ComposMap,
+    obj: MapObject,
+    collection: str,
+) -> ComposMap:
+    """Return a new ComposMap with obj replacing the same-ID object in collection."""
+    items = getattr(compos_map, collection)
+    new_items = tuple(obj if item.id == obj.id else item for item in items)
+    return _build_map_with(compos_map, collection, new_items)
+
+
+def _add_to_collection(
+    compos_map: ComposMap,
+    obj: MapObject,
+    collection: str,
+) -> ComposMap:
+    """Return a new ComposMap with obj appended to collection."""
+    items = getattr(compos_map, collection)
+    new_items = items + (obj,)
+    return _build_map_with(compos_map, collection, new_items)
+
+
+def _apply_version_bump(compos_map: ComposMap, bump: VersionBump) -> ComposMap:
+    """Return a new ComposMap with version bump applied."""
+    data = compos_map.model_dump(by_alias=False)
+    data["map_version"] = bump.new_version
+    data["generated_at"] = bump.generated_at
+    data["parent_version"] = bump.parent_version
+    if bump.git_commit is not None:
+        data["git_commit"] = bump.git_commit
+    return ComposMap.model_validate(data)
+
+
+def _normalize_source(source: ProvenanceSource | Any) -> str:
+    """Normalize provenance source to string for priority lookup.
+
+    Handles both ProvenanceSource and DecisionProvenanceSource.
+    """
+    return str(source.value) if hasattr(source, "value") else str(source)
+
+
+def _to_provenance_source(source_str: str) -> ProvenanceSource:
+    """Convert a source string to ProvenanceSource enum.
+
+    Works for both ProvenanceSource and DecisionProvenanceSource values
+    since they share the same string values (minus static-analysis).
+    """
+    return ProvenanceSource(source_str)
+
+
+# ---------------------------------------------------------------------------
+# Generic pipeline functions
+# ---------------------------------------------------------------------------
+
+
+def _execute_register(
+    current_map: ComposMap,
+    obj: MapObject,
+    git_commit: str | None = None,
+) -> WriteResult:
+    """Pipeline for REGISTER operations."""
+    collection = _TYPE_TO_COLLECTION[type(obj)]
+    type_name = _TYPE_TO_NAME[type(obj)]
+
+    # Stage 3: ID uniqueness
+    uniqueness_violation = check_id_uniqueness(current_map, obj.id, collection)
+    if uniqueness_violation is not None:
+        return _fail("uniqueness", uniqueness_violation.message, uniqueness_violation)
+
+    # Stage 4: Referential integrity
+    integrity_violations = check_referential_integrity(current_map, obj)
+    if integrity_violations:
+        messages = [v.message for v in integrity_violations]
+        return _fail(
+            "integrity",
+            f"Referential integrity violations: {'; '.join(messages)}",
+            integrity_violations,
+        )
+
+    # Stage 5: Structural safety (relationships only — cycle detection)
+    if isinstance(obj, Relationship):
+        eval_result = evaluate_proposed_change(
+            current_map, proposed_relationships=(obj,)
+        )
+        if eval_result.cycles:
+            cycle_desc = "; ".join(
+                f"cycle: {' -> '.join(c.component_ids)}" for c in eval_result.cycles
+            )
+            return _fail(
+                "structural",
+                f"Relationship would introduce cycle(s): {cycle_desc}",
+                eval_result.cycles,
+            )
+
+    # All checks passed — build new map
+    new_map = _add_to_collection(current_map, obj, collection)
+
+    # Version bump
+    bump = increment_version(current_map, git_commit=git_commit)
+    new_map = _apply_version_bump(new_map, bump)
+
+    # Merge log entry (no merge for register)
+    source_str = _normalize_source(obj.provenance.source)
+    log_entry = create_entry(
+        version_bump=bump,
+        operation=f"register_{type_name}",
+        target_id=obj.id,
+        target_type=type_name,
+        source=_to_provenance_source(source_str),
+        merge_result=None,
+    )
+
+    return WriteResult(
+        success=True,
+        new_map=new_map,
+        new_version=bump.new_version,
+        merge_summary=log_entry,
+        errors=(),
+        warnings=(),
+    )
+
+
+def _execute_update(
+    current_map: ComposMap,
+    obj: MapObject,
+    git_commit: str | None = None,
+) -> WriteResult:
+    """Pipeline for UPDATE operations."""
+    type_name = _TYPE_TO_NAME[type(obj)]
+    collection = _TYPE_TO_COLLECTION[type(obj)]
+
+    # Find existing
+    existing = _find_existing(current_map, obj.id, type(obj))
+    if existing is None:
+        return _fail("not_found", f"{type_name} '{obj.id}' not found")
+
+    # Stage 4: Referential integrity (on the incoming object)
+    integrity_violations = check_referential_integrity(current_map, obj)
+    if integrity_violations:
+        messages = [v.message for v in integrity_violations]
+        return _fail(
+            "integrity",
+            f"Referential integrity violations: {'; '.join(messages)}",
+            integrity_violations,
+        )
+
+    # Stage 6: Merge engine
+    merge_result = merge_object(existing, obj)
+
+    # Build new map with merged object
+    new_map = _replace_in_collection(current_map, merge_result.merged_obj, collection)
+
+    # Version bump
+    bump = increment_version(current_map, git_commit=git_commit)
+    new_map = _apply_version_bump(new_map, bump)
+
+    # Merge log entry
+    source_str = _normalize_source(obj.provenance.source)
+    log_entry = create_entry(
+        version_bump=bump,
+        operation=f"update_{type_name}",
+        target_id=obj.id,
+        target_type=type_name,
+        source=_to_provenance_source(source_str),
+        merge_result=merge_result,
+    )
+
+    # Collect warnings
+    warnings: list[str] = []
+    for record in merge_result.field_records:
+        if record.resolution.value == "warning":
+            warnings.append(record.reason)
+        elif record.resolution.value == "rejected":
+            warnings.append(
+                f"Field '{record.field_name}' rejected: {record.reason}"
+            )
+
+    return WriteResult(
+        success=True,
+        new_map=new_map,
+        new_version=bump.new_version,
+        merge_summary=log_entry,
+        errors=(),
+        warnings=tuple(warnings),
+    )
+
+
+def _execute_remove(
+    current_map: ComposMap,
+    obj_id: str,
+    obj_type: type,
+    reason: str,
+    caller_source: ProvenanceSource = ProvenanceSource.HUMAN_INPUT,
+    git_commit: str | None = None,
+) -> WriteResult:
+    """Pipeline for REMOVE operations.
+
+    Provenance-gated: caller_source must be >= the object's provenance source
+    in the trust hierarchy. If not, removal is rejected with a warning.
+    """
+    type_name = _TYPE_TO_NAME[obj_type]
+    collection = _TYPE_TO_COLLECTION[obj_type]
+
+    # Find existing
+    existing = _find_existing(current_map, obj_id, obj_type)
+    if existing is None:
+        return _fail("not_found", f"{type_name} '{obj_id}' not found")
+
+    # Provenance gate: check caller has sufficient priority
+    source_str = _normalize_source(existing.provenance.source)
+    existing_source = _to_provenance_source(source_str)
+    existing_priority = _SOURCE_PRIORITY[existing_source]
+    caller_priority = _SOURCE_PRIORITY[caller_source]
+
+    if caller_priority < existing_priority:
+        return _fail(
+            "provenance",
+            (
+                f"Cannot remove {type_name} '{obj_id}': created by "
+                f"{existing_source.value}, caller is {caller_source.value}. "
+                f"Flagged for human review."
+            ),
+        )
+
+    # Stage 4: Check remove blocked (impact report)
+    blocked = check_remove_blocked(current_map, obj_id, type_name)
+    if blocked:
+        blocking_desc = ", ".join(
+            f"{b.object_type}:{b.object_id}" for b in blocked
+        )
+        return _fail(
+            "integrity",
+            f"Cannot remove {type_name} '{obj_id}': referenced by {blocking_desc}",
+            blocked,
+        )
+
+    # Build soft-deleted object — type-aware status and fields
+    now = datetime.now(UTC)
+    existing_data = existing.model_dump(by_alias=False)
+    existing_data["status"] = _TYPE_TO_REMOVED_STATUS[obj_type]
+    existing_data["removed_at"] = now
+    existing_data["removed_reason"] = reason
+    removed_obj = type(existing).model_validate(existing_data)
+
+    # Build new map
+    new_map = _replace_in_collection(current_map, removed_obj, collection)
+
+    # Version bump
+    bump = increment_version(current_map, git_commit=git_commit)
+    new_map = _apply_version_bump(new_map, bump)
+
+    # Merge log entry
+    log_entry = create_entry(
+        version_bump=bump,
+        operation=f"remove_{type_name}",
+        target_id=obj_id,
+        target_type=type_name,
+        source=existing_source,
+        merge_result=None,
+    )
+
+    return WriteResult(
+        success=True,
+        new_map=new_map,
+        new_version=bump.new_version,
+        merge_summary=log_entry,
+        errors=(),
+        warnings=(),
+    )
+
+
+# ---------------------------------------------------------------------------
+# Type-specific public entry points
+# ---------------------------------------------------------------------------
+
+
+def register_component(
+    current_map: ComposMap,
+    component: Component,
+    git_commit: str | None = None,
+) -> WriteResult:
+    return _execute_register(current_map, component, git_commit)
+
+
+def register_relationship(
+    current_map: ComposMap,
+    relationship: Relationship,
+    git_commit: str | None = None,
+) -> WriteResult:
+    return _execute_register(current_map, relationship, git_commit)
+
+
+def register_constraint(
+    current_map: ComposMap,
+    constraint: Constraint,
+    git_commit: str | None = None,
+) -> WriteResult:
+    return _execute_register(current_map, constraint, git_commit)
+
+
+def register_risk(
+    current_map: ComposMap,
+    risk: Risk,
+    git_commit: str | None = None,
+) -> WriteResult:
+    return _execute_register(current_map, risk, git_commit)
+
+
+def register_decision(
+    current_map: ComposMap,
+    decision: Decision,
+    git_commit: str | None = None,
+) -> WriteResult:
+    return _execute_register(current_map, decision, git_commit)
+
+
+def update_component(
+    current_map: ComposMap,
+    component: Component,
+    git_commit: str | None = None,
+) -> WriteResult:
+    return _execute_update(current_map, component, git_commit)
+
+
+def update_relationship(
+    current_map: ComposMap,
+    relationship: Relationship,
+    git_commit: str | None = None,
+) -> WriteResult:
+    return _execute_update(current_map, relationship, git_commit)
+
+
+def update_constraint(
+    current_map: ComposMap,
+    constraint: Constraint,
+    git_commit: str | None = None,
+) -> WriteResult:
+    return _execute_update(current_map, constraint, git_commit)
+
+
+def update_risk(
+    current_map: ComposMap,
+    risk: Risk,
+    git_commit: str | None = None,
+) -> WriteResult:
+    return _execute_update(current_map, risk, git_commit)
+
+
+def update_decision(
+    current_map: ComposMap,
+    decision: Decision,
+    git_commit: str | None = None,
+) -> WriteResult:
+    return _execute_update(current_map, decision, git_commit)
+
+
+def remove_component(
+    current_map: ComposMap,
+    component_id: str,
+    reason: str,
+    caller_source: ProvenanceSource = ProvenanceSource.HUMAN_INPUT,
+    git_commit: str | None = None,
+) -> WriteResult:
+    return _execute_remove(
+        current_map, component_id, Component, reason, caller_source, git_commit,
+    )
+
+
+def remove_relationship(
+    current_map: ComposMap,
+    relationship_id: str,
+    reason: str,
+    caller_source: ProvenanceSource = ProvenanceSource.HUMAN_INPUT,
+    git_commit: str | None = None,
+) -> WriteResult:
+    return _execute_remove(
+        current_map, relationship_id, Relationship, reason, caller_source, git_commit,
+    )
+
+
+def remove_constraint(
+    current_map: ComposMap,
+    constraint_id: str,
+    reason: str,
+    caller_source: ProvenanceSource = ProvenanceSource.HUMAN_INPUT,
+    git_commit: str | None = None,
+) -> WriteResult:
+    return _execute_remove(
+        current_map, constraint_id, Constraint, reason, caller_source, git_commit,
+    )
+
+
+def remove_risk(
+    current_map: ComposMap,
+    risk_id: str,
+    reason: str,
+    caller_source: ProvenanceSource = ProvenanceSource.HUMAN_INPUT,
+    git_commit: str | None = None,
+) -> WriteResult:
+    return _execute_remove(
+        current_map, risk_id, Risk, reason, caller_source, git_commit,
+    )
+
+
+def remove_decision(
+    current_map: ComposMap,
+    decision_id: str,
+    reason: str,
+    caller_source: ProvenanceSource = ProvenanceSource.HUMAN_INPUT,
+    git_commit: str | None = None,
+) -> WriteResult:
+    return _execute_remove(
+        current_map, decision_id, Decision, reason, caller_source, git_commit,
+    )

compos/schema/__init__.py

@@ -0,0 +1,57 @@
+"""Schema package — Pydantic models for the Compos architectural map."""
+
+from compos.schema.models import (
+    AlternativeConsidered,
+    Component,
+    ComponentType,
+    ComposMap,
+    Constraint,
+    ConstraintStatus,
+    ConstraintType,
+    Decision,
+    DecisionProvenance,
+    DecisionProvenanceSource,
+    DecisionStatus,
+    Hardness,
+    LastMerge,
+    Likelihood,
+    ObjectStatus,
+    ProjectInfo,
+    Provenance,
+    ProvenanceSource,
+    Relationship,
+    RelationshipPattern,
+    RelationshipType,
+    Risk,
+    RiskStatus,
+    Severity,
+)
+
+__all__ = [
+    # Enums
+    "ComponentType",
+    "ConstraintStatus",
+    "ConstraintType",
+    "DecisionProvenanceSource",
+    "DecisionStatus",
+    "Hardness",
+    "Likelihood",
+    "ObjectStatus",
+    "ProvenanceSource",
+    "RelationshipPattern",
+    "RelationshipType",
+    "RiskStatus",
+    "Severity",
+    # Models
+    "AlternativeConsidered",
+    "Component",
+    "ComposMap",
+    "Constraint",
+    "Decision",
+    "DecisionProvenance",
+    "LastMerge",
+    "ProjectInfo",
+    "Provenance",
+    "Relationship",
+    "Risk",
+]