__init__.py
python
sha256:81ae324db5ad375fbfe4834c6fcb378312cafad3cc92dec5d3e5c427306621a2
fix: remove commit_exists filter from have anchors — server…
Sonnet 4.6
patch
22 days ago
| 1 | """muse harmony — Resolution Intelligence for domain-agnostic conflict resolution. |
| 2 | |
| 3 | Harmony is a three-tier resolution intelligence layer built from the ground up |
| 4 | for an agent-first, multi-dimensional VCS. |
| 5 | |
| 6 | Core concepts |
| 7 | ------------- |
| 8 | |
| 9 | ConflictPattern |
| 10 | The semantic identity of a divergence between two branches. Every pattern |
| 11 | carries both a *blob fingerprint* (SHA-256 of sorted object-ID pair, for |
| 12 | exact matching) and a *semantic fingerprint* (domain-provided, for fuzzy |
| 13 | matching across structurally similar conflicts). The two fingerprints |
| 14 | allow exact replay as a degenerate case of the richer semantic model. |
| 15 | |
| 16 | Resolution |
| 17 | A committed decision: what the resolved state is, who made it, which |
| 18 | strategy was applied, and a human-readable rationale. ``applied_count`` |
| 19 | tracks replay frequency and informs confidence ranking. |
| 20 | |
| 21 | Policy |
| 22 | A declarative rule that fires automatically when a conflict pattern matches |
| 23 | its condition. Conditions constrain ``conflict_type``, ``domain``, path |
| 24 | glob, and minimum confidence. Policies are evaluated in scope order: |
| 25 | workspace → repo → domain → file. The first matching policy wins. |
| 26 | |
| 27 | ResolutionProposal |
| 28 | A candidate resolution returned by the harmony engine when no exact match |
| 29 | exists but a semantic or policy match is available. Always carries a |
| 30 | ``confidence`` score so agents can decide whether to auto-accept or escalate. |
| 31 | |
| 32 | Resolution engine (Phase 3) |
| 33 | The engine evaluates conflicts in this order: |
| 34 | 1. Policy match — declarative rule fires automatically. |
| 35 | 2. Exact replay — blob fingerprint matches a saved resolution. |
| 36 | 3. Semantic match — domain plugin similarity score ≥ threshold. |
| 37 | 4. Escalate — create hub issue, flag for human or specialist agent. |
| 38 | |
| 39 | Storage layout |
| 40 | -------------- |
| 41 | |
| 42 | :: |
| 43 | |
| 44 | .muse/harmony/ |
| 45 | policies/ |
| 46 | <policy_id>.json ← one file per policy (Phase 2 migrates to TOML) |
| 47 | patterns/ |
| 48 | <pattern_id>/ |
| 49 | pattern.json ← ConflictPattern metadata |
| 50 | resolutions/ |
| 51 | <resolution_id>.json ← one Resolution per file |
| 52 | audit/ |
| 53 | <YYYYMMDD>-<sha256-hex-slice>.json ← append-only audit log |
| 54 | |
| 55 | Security model |
| 56 | -------------- |
| 57 | |
| 58 | Pattern and resolution IDs are validated as exactly 64 lowercase hex characters |
| 59 | before any filesystem path is constructed — preventing ``../`` path-traversal. |
| 60 | Policy IDs are validated as URL-safe alphanumeric strings. All directory |
| 61 | iteration skips symlinks. File reads are capped at :data:`_MAX_PATTERN_BYTES`, |
| 62 | :data:`_MAX_RESOLUTION_BYTES`, and :data:`_MAX_POLICY_BYTES` to prevent OOM |
| 63 | from maliciously large entries. All writes are atomic (temp file + ``os.replace``). |
| 64 | |
| 65 | Thread safety |
| 66 | ------------- |
| 67 | |
| 68 | All writes use ``os.replace`` (POSIX rename), which is atomic on all supported |
| 69 | platforms. Concurrent readers always see either a complete or absent file — |
| 70 | never a partial write. |
| 71 | |
| 72 | Extensibility |
| 73 | ------------- |
| 74 | |
| 75 | :class:`ConflictType`, :class:`ResolutionStrategy`, :class:`PolicyAction`, and |
| 76 | :class:`PolicyScope` are open string-constant namespaces rather than closed |
| 77 | enums. Domain plugins may define additional constants (e.g. ``"note_collision"``, |
| 78 | ``"tempo_divergence"``) without modifying this module. |
| 79 | |
| 80 | Package structure |
| 81 | ----------------- |
| 82 | |
| 83 | :mod:`muse.core.harmony.types` — dataclasses, TypedDicts, enums |
| 84 | :mod:`muse.core.harmony.paths` — path helpers and path-level validation |
| 85 | :mod:`muse.core.harmony.fingerprint` — blob / semantic fingerprint computation |
| 86 | :mod:`muse.core.harmony.patterns` — ConflictPattern CRUD |
| 87 | :mod:`muse.core.harmony.resolutions` — Resolution CRUD and GC |
| 88 | :mod:`muse.core.harmony.audit` — append-only audit log |
| 89 | :mod:`muse.core.harmony.policies` — Policy CRUD and matching |
| 90 | :mod:`muse.core.harmony.escalations` — EscalationRecord CRUD |
| 91 | :mod:`muse.core.harmony.engine` — three-tier resolution engine |
| 92 | |
| 93 | This ``__init__.py`` re-exports the full public API so all existing |
| 94 | ``from muse.core.harmony import X`` statements continue to work unchanged. |
| 95 | """ |
| 96 | |
| 97 | from __future__ import annotations |
| 98 | |
| 99 | from .fingerprint import ( |
| 100 | _now_utc, |
| 101 | _parse_dt, |
| 102 | blob_fingerprint, |
| 103 | compute_pattern_id, |
| 104 | compute_resolution_id, |
| 105 | compute_escalation_id, |
| 106 | compute_semantic_fingerprint, |
| 107 | ) |
| 108 | from .patterns import ( |
| 109 | _MAX_PATTERN_BYTES, |
| 110 | _MAX_SCAN, |
| 111 | _write_atomic, |
| 112 | _pattern_to_dict, |
| 113 | _dict_to_pattern, |
| 114 | record_pattern, |
| 115 | load_pattern, |
| 116 | list_patterns, |
| 117 | forget_pattern, |
| 118 | clear_all, |
| 119 | ) |
| 120 | from .resolutions import ( |
| 121 | _MAX_RESOLUTION_BYTES, |
| 122 | _resolution_to_dict, |
| 123 | _dict_to_resolution, |
| 124 | save_resolution, |
| 125 | load_resolution, |
| 126 | list_resolutions, |
| 127 | increment_applied_count, |
| 128 | best_resolution, |
| 129 | gc_stale, |
| 130 | ) |
| 131 | from .audit import ( |
| 132 | _MAX_AUDIT_BYTES, |
| 133 | _MAX_AUDIT_ENTRIES, |
| 134 | append_audit, |
| 135 | list_audit, |
| 136 | ) |
| 137 | from .policies import ( |
| 138 | _MAX_POLICY_BYTES, |
| 139 | _MAX_POLICIES, |
| 140 | _policy_condition_to_dict, |
| 141 | _policy_to_dict, |
| 142 | _dict_to_policy, |
| 143 | save_policy, |
| 144 | load_policy, |
| 145 | list_policies, |
| 146 | remove_policy, |
| 147 | _condition_matches, |
| 148 | match_policy, |
| 149 | ) |
| 150 | from .escalations import ( |
| 151 | _MAX_ESCALATION_BYTES, |
| 152 | _escalation_to_dict, |
| 153 | _dict_to_escalation, |
| 154 | record_escalation, |
| 155 | load_escalation, |
| 156 | list_escalations, |
| 157 | resolve_escalation, |
| 158 | ) |
| 159 | from .paths import ( |
| 160 | _HARMONY, |
| 161 | _PATTERNS, |
| 162 | _POLICIES, |
| 163 | _AUDIT, |
| 164 | _ESCALATIONS, |
| 165 | _RESOLUTIONS, |
| 166 | _PATTERN_FILE, |
| 167 | _MAX_FINGERPRINT_BYTES, |
| 168 | _SHA256_ID_RE, |
| 169 | _BARE_HEX64_RE, |
| 170 | _POLICY_ID_RE, |
| 171 | patterns_dir, |
| 172 | policies_dir, |
| 173 | audit_dir, |
| 174 | escalations_dir, |
| 175 | escalation_path, |
| 176 | pattern_dir, |
| 177 | _pattern_entry_dir, |
| 178 | _resolutions_dir, |
| 179 | resolution_path, |
| 180 | _resolution_path, |
| 181 | _validate_id, |
| 182 | _validate_fingerprint, |
| 183 | _validate_policy_id, |
| 184 | ) |
| 185 | from .types import ( |
| 186 | _ConflictDescription, |
| 187 | _AuditMetadata, |
| 188 | _ProvenanceDict, |
| 189 | ConflictType, |
| 190 | ResolutionStrategy, |
| 191 | PolicyAction, |
| 192 | PolicyScope, |
| 193 | AuditEventType, |
| 194 | EscalationStatus, |
| 195 | AgentProvenance, |
| 196 | PolicyCondition, |
| 197 | ConflictPattern, |
| 198 | Resolution, |
| 199 | Policy, |
| 200 | ResolutionProposal, |
| 201 | EscalationRecord, |
| 202 | _PatternDict, |
| 203 | _ResolutionDict, |
| 204 | _PolicyConditionDict, |
| 205 | _PolicyDict, |
| 206 | AuditEvent, |
| 207 | _EscalationDict, |
| 208 | ) |
| 209 | from .engine import ( |
| 210 | EngineStatus, |
| 211 | HarmonyPlugin, |
| 212 | DefaultPlugin, |
| 213 | EngineConfig, |
| 214 | EngineResult, |
| 215 | find_similar, |
| 216 | resolve, |
| 217 | auto_apply, |
| 218 | record_resolutions, |
| 219 | ) |
File History
2 commits
sha256:81ae324db5ad375fbfe4834c6fcb378312cafad3cc92dec5d3e5c427306621a2
fix: remove commit_exists filter from have anchors — server…
Sonnet 4.6
patch
22 days ago
sha256:36c3cb3e76619d4c30a6d9bf81b5ec4ff148e30dcfed913e3114ca7b43b81c7e
fix: rename objects→blobs in push client and all stale test…
Sonnet 4.6
patch
23 days ago