diff --git hermes-agent/docs/api/architecture-document-v1.schema.json harness/docs/api/architecture-document-v1.schema.json
new file mode 100644
index 0000000000000000000000000000000000000000..5064ff5d60c9dc5ff3a3a1509de15970ef9ff517
--- /dev/null
+++ harness/docs/api/architecture-document-v1.schema.json
@@ -0,0 +1,1344 @@
+{
+ "$defs": {
+ "ci": {
+ "properties": {
+ "architectural": {
+ "type": "object"
+ },
+ "edges": {
+ "items": {
+ "properties": {
+ "kind": {
+ "pattern": "^\\S.*$",
+ "type": "string"
+ },
+ "label": {
+ "type": "string"
+ },
+ "source": {
+ "pattern": "^\\S.*$",
+ "type": "string"
+ },
+ "target": {
+ "pattern": "^\\S.*$",
+ "type": "string"
+ }
+ },
+ "required": [
+ "source",
+ "target",
+ "kind"
+ ],
+ "type": "object"
+ },
+ "type": "array"
+ },
+ "families": {
+ "type": "object"
+ },
+ "jobs": {
+ "items": {
+ "$ref": "#/$defs/ci_job"
+ },
+ "minItems": 1,
+ "type": "array"
+ },
+ "limitations": {
+ "items": {
+ "type": "string"
+ },
+ "type": "array"
+ },
+ "merge": {
+ "properties": {
+ "id": {
+ "pattern": "^\\S.*$",
+ "type": "string"
+ },
+ "inputs": {
+ "items": {
+ "pattern": "^\\S.*$",
+ "type": "string"
+ },
+ "minItems": 1,
+ "type": "array"
+ },
+ "label": {
+ "type": "string"
+ }
+ },
+ "required": [
+ "id",
+ "label",
+ "inputs"
+ ],
+ "type": "object"
+ },
+ "ratchets": {
+ "items": {
+ "$ref": "#/$defs/ci_ratchet"
+ },
+ "type": "array"
+ },
+ "static_checks": {
+ "items": {
+ "properties": {
+ "command": {
+ "type": "string"
+ },
+ "evidence": {
+ "$ref": "#/$defs/evidence"
+ },
+ "job": {
+ "pattern": "^\\S.*$",
+ "type": "string"
+ },
+ "name": {
+ "type": "string"
+ },
+ "scripts": {
+ "items": {
+ "type": "string"
+ },
+ "type": "array"
+ }
+ },
+ "required": [
+ "name",
+ "command",
+ "job"
+ ],
+ "type": "object"
+ },
+ "type": "array"
+ },
+ "summary": {
+ "properties": {
+ "gates": {
+ "minimum": 0,
+ "type": "integer"
+ },
+ "jobs": {
+ "minimum": 0,
+ "type": "integer"
+ },
+ "ratchets": {
+ "minimum": 0,
+ "type": "integer"
+ },
+ "static_checks": {
+ "minimum": 0,
+ "type": "integer"
+ },
+ "workflows": {
+ "minimum": 0,
+ "type": "integer"
+ }
+ },
+ "required": [
+ "workflows",
+ "jobs",
+ "gates"
+ ],
+ "type": "object"
+ },
+ "triggers": {
+ "items": {
+ "properties": {
+ "event": {
+ "type": "string"
+ },
+ "id": {
+ "pattern": "^\\S.*$",
+ "type": "string"
+ },
+ "workflows": {
+ "items": {
+ "type": "string"
+ },
+ "type": "array"
+ }
+ },
+ "required": [
+ "id",
+ "event",
+ "workflows"
+ ],
+ "type": "object"
+ },
+ "type": "array"
+ },
+ "workflows": {
+ "items": {
+ "$ref": "#/$defs/ci_workflow"
+ },
+ "minItems": 1,
+ "type": "array"
+ }
+ },
+ "required": [
+ "workflows",
+ "jobs",
+ "edges",
+ "merge",
+ "ratchets",
+ "static_checks",
+ "summary"
+ ],
+ "type": "object"
+ },
+ "ci_job": {
+ "properties": {
+ "artifacts_in": {
+ "items": {
+ "type": "string"
+ },
+ "type": "array"
+ },
+ "artifacts_out": {
+ "items": {
+ "type": "string"
+ },
+ "type": "array"
+ },
+ "condition": {
+ "type": [
+ "string",
+ "null"
+ ]
+ },
+ "evidence": {
+ "$ref": "#/$defs/evidence"
+ },
+ "family": {
+ "pattern": "^\\S.*$",
+ "type": "string"
+ },
+ "id": {
+ "pattern": "^\\S.*$",
+ "type": "string"
+ },
+ "key": {
+ "type": "string"
+ },
+ "name": {
+ "type": "string"
+ },
+ "needs": {
+ "items": {
+ "type": "string"
+ },
+ "type": "array"
+ },
+ "pins": {
+ "type": "array"
+ },
+ "role": {
+ "enum": [
+ "gate",
+ "post-merge",
+ "manual",
+ "disabled",
+ "local"
+ ],
+ "type": "string"
+ },
+ "runs_on": {
+ "type": "string"
+ },
+ "scripts": {
+ "items": {
+ "type": "string"
+ },
+ "type": "array"
+ },
+ "step_count": {
+ "minimum": 0,
+ "type": "integer"
+ },
+ "steps": {
+ "type": "array"
+ },
+ "workflow": {
+ "pattern": "^\\S.*$",
+ "type": "string"
+ }
+ },
+ "required": [
+ "id",
+ "name",
+ "workflow",
+ "family",
+ "role",
+ "needs"
+ ],
+ "type": "object"
+ },
+ "ci_ratchet": {
+ "properties": {
+ "current": {
+ "type": "object"
+ },
+ "floor": {
+ "type": "string"
+ },
+ "id": {
+ "pattern": "^\\S.*$",
+ "type": "string"
+ },
+ "job": {
+ "pattern": "^\\S.*$",
+ "type": "string"
+ },
+ "measures": {
+ "type": "string"
+ },
+ "patch": {
+ "type": [
+ "string",
+ "null"
+ ]
+ },
+ "source": {
+ "type": "object"
+ },
+ "source_path": {
+ "type": "string"
+ },
+ "title": {
+ "type": "string"
+ }
+ },
+ "required": [
+ "id",
+ "title",
+ "job",
+ "measures",
+ "floor"
+ ],
+ "type": "object"
+ },
+ "ci_workflow": {
+ "properties": {
+ "events": {
+ "items": {
+ "type": "string"
+ },
+ "type": "array"
+ },
+ "family": {
+ "pattern": "^\\S.*$",
+ "type": "string"
+ },
+ "id": {
+ "pattern": "^\\S.*$",
+ "type": "string"
+ },
+ "jobs": {
+ "items": {
+ "type": "string"
+ },
+ "type": "array"
+ },
+ "label": {
+ "type": "string"
+ },
+ "name": {
+ "type": "string"
+ },
+ "path": {
+ "type": "string"
+ },
+ "question": {
+ "type": "string"
+ }
+ },
+ "required": [
+ "id",
+ "label",
+ "family",
+ "jobs"
+ ],
+ "type": "object"
+ },
+ "component": {
+ "properties": {
+ "declaration_count": {
+ "minimum": 0,
+ "type": "integer"
+ },
+ "declarations": {
+ "items": {
+ "type": "string"
+ },
+ "type": "array"
+ },
+ "description": {
+ "type": "string"
+ },
+ "external": {
+ "type": "boolean"
+ },
+ "file_count": {
+ "minimum": 0,
+ "type": "integer"
+ },
+ "files": {
+ "items": {
+ "type": "string"
+ },
+ "type": "array"
+ },
+ "id": {
+ "pattern": "^\\S.*$",
+ "type": "string"
+ },
+ "label": {
+ "type": "string"
+ },
+ "layer": {
+ "type": "string"
+ },
+ "line_count": {
+ "minimum": 0,
+ "type": "integer"
+ }
+ },
+ "required": [
+ "id",
+ "label",
+ "description",
+ "files",
+ "declarations",
+ "file_count",
+ "line_count",
+ "declaration_count"
+ ],
+ "type": "object"
+ },
+ "evidence": {
+ "properties": {
+ "excerpt": {
+ "type": "string"
+ },
+ "line": {
+ "minimum": 1,
+ "type": "integer"
+ },
+ "path": {
+ "type": "string"
+ }
+ },
+ "required": [
+ "path",
+ "line"
+ ],
+ "type": "object"
+ },
+ "external": {
+ "properties": {
+ "category": {
+ "type": "string"
+ },
+ "component": {
+ "type": [
+ "string",
+ "null"
+ ]
+ },
+ "description": {
+ "type": "string"
+ },
+ "file_count": {
+ "minimum": 0,
+ "type": "integer"
+ },
+ "hit_count": {
+ "minimum": 0,
+ "type": "integer"
+ },
+ "id": {
+ "pattern": "^\\S.*$",
+ "type": "string"
+ },
+ "label": {
+ "type": "string"
+ }
+ },
+ "required": [
+ "id",
+ "label",
+ "category"
+ ],
+ "type": "object"
+ },
+ "extraction": {
+ "properties": {
+ "authority": {
+ "enum": [
+ "observed",
+ "declared"
+ ],
+ "type": "string"
+ },
+ "derivation": {
+ "type": "string"
+ },
+ "entities": {
+ "items": {
+ "$ref": "#/$defs/extraction_entity"
+ },
+ "minItems": 1,
+ "type": "array"
+ },
+ "families": {
+ "type": "object"
+ },
+ "files": {
+ "items": {
+ "$ref": "#/$defs/extraction_file"
+ },
+ "minItems": 1,
+ "type": "array"
+ },
+ "passes": {
+ "items": {
+ "$ref": "#/$defs/extraction_pass"
+ },
+ "minItems": 1,
+ "type": "array"
+ },
+ "summary": {
+ "properties": {
+ "by_kind": {
+ "type": "object"
+ },
+ "citations": {
+ "minimum": 0,
+ "type": "integer"
+ },
+ "declarations": {
+ "minimum": 0,
+ "type": "integer"
+ },
+ "entities": {
+ "minimum": 0,
+ "type": "integer"
+ },
+ "entities_with_origin": {
+ "minimum": 0,
+ "type": "integer"
+ },
+ "files": {
+ "minimum": 0,
+ "type": "integer"
+ },
+ "functions": {
+ "type": "object"
+ },
+ "mapped_declarations": {
+ "minimum": 0,
+ "type": "integer"
+ },
+ "passes": {
+ "minimum": 0,
+ "type": "integer"
+ },
+ "semantic_citations": {
+ "minimum": 0,
+ "type": "integer"
+ },
+ "touched_files": {
+ "minimum": 0,
+ "type": "integer"
+ },
+ "types": {
+ "type": "object"
+ },
+ "untouched_files": {
+ "minimum": 0,
+ "type": "integer"
+ }
+ },
+ "required": [
+ "files",
+ "touched_files",
+ "untouched_files",
+ "declarations",
+ "mapped_declarations",
+ "entities",
+ "entities_with_origin",
+ "passes"
+ ],
+ "type": "object"
+ }
+ },
+ "required": [
+ "authority",
+ "derivation",
+ "files",
+ "passes",
+ "entities",
+ "summary"
+ ],
+ "type": "object"
+ },
+ "extraction_entity": {
+ "properties": {
+ "component": {
+ "type": [
+ "string",
+ "null"
+ ]
+ },
+ "id": {
+ "pattern": "^\\S.*$",
+ "type": "string"
+ },
+ "kind": {
+ "pattern": "^\\S.*$",
+ "type": "string"
+ },
+ "label": {
+ "type": "string"
+ },
+ "origins": {
+ "items": {
+ "properties": {
+ "family": {
+ "pattern": "^\\S.*$",
+ "type": "string"
+ },
+ "line": {
+ "minimum": 1,
+ "type": "integer"
+ },
+ "path": {
+ "type": "string"
+ },
+ "rule": {
+ "pattern": "^\\S.*$",
+ "type": "string"
+ },
+ "via": {
+ "type": "string"
+ }
+ },
+ "required": [
+ "path",
+ "line",
+ "rule",
+ "family"
+ ],
+ "type": "object"
+ },
+ "minItems": 1,
+ "type": "array"
+ }
+ },
+ "required": [
+ "id",
+ "kind",
+ "label",
+ "origins"
+ ],
+ "type": "object"
+ },
+ "extraction_file": {
+ "properties": {
+ "citations": {
+ "minimum": 0,
+ "type": "integer"
+ },
+ "component": {
+ "type": [
+ "string",
+ "null"
+ ]
+ },
+ "declaration_count": {
+ "minimum": 0,
+ "type": "integer"
+ },
+ "declarations": {
+ "items": {
+ "properties": {
+ "kind": {
+ "pattern": "^\\S.*$",
+ "type": "string"
+ },
+ "line": {
+ "minimum": 1,
+ "type": "integer"
+ },
+ "name": {
+ "type": "string"
+ },
+ "passes": {
+ "items": {
+ "type": "string"
+ },
+ "type": "array"
+ }
+ },
+ "required": [
+ "kind",
+ "name",
+ "line",
+ "passes"
+ ],
+ "type": "object"
+ },
+ "type": "array"
+ },
+ "line_count": {
+ "minimum": 0,
+ "type": "integer"
+ },
+ "mapped_declarations": {
+ "minimum": 0,
+ "type": "integer"
+ },
+ "passes": {
+ "items": {
+ "type": "string"
+ },
+ "type": "array"
+ },
+ "path": {
+ "type": "string"
+ },
+ "semantic_citations": {
+ "minimum": 0,
+ "type": "integer"
+ },
+ "touched": {
+ "type": "boolean"
+ }
+ },
+ "required": [
+ "path",
+ "line_count",
+ "declarations",
+ "passes",
+ "citations",
+ "touched",
+ "declaration_count",
+ "mapped_declarations"
+ ],
+ "type": "object"
+ },
+ "extraction_pass": {
+ "properties": {
+ "citations": {
+ "minimum": 0,
+ "type": "integer"
+ },
+ "class": {
+ "enum": [
+ "mechanical",
+ "semantic"
+ ],
+ "type": "string"
+ },
+ "description": {
+ "type": "string"
+ },
+ "files": {
+ "minimum": 0,
+ "type": "integer"
+ },
+ "id": {
+ "pattern": "^\\S.*$",
+ "type": "string"
+ }
+ },
+ "required": [
+ "id",
+ "class",
+ "description",
+ "files",
+ "citations"
+ ],
+ "type": "object"
+ },
+ "flow": {
+ "properties": {
+ "authority": {
+ "type": "string"
+ },
+ "evidence": {
+ "items": {
+ "$ref": "#/$defs/evidence"
+ },
+ "type": "array"
+ },
+ "id": {
+ "pattern": "^\\S.*$",
+ "type": "string"
+ },
+ "interaction": {
+ "type": "string"
+ },
+ "journey": {
+ "type": "string"
+ },
+ "outcome": {
+ "type": "string"
+ },
+ "page": {
+ "type": [
+ "string",
+ "null"
+ ]
+ },
+ "status": {
+ "type": "string"
+ },
+ "steps": {
+ "items": {
+ "properties": {
+ "from": {
+ "pattern": "^\\S.*$",
+ "type": "string"
+ },
+ "note": {
+ "type": "string"
+ },
+ "relation": {
+ "pattern": "^\\S.*$",
+ "type": "string"
+ },
+ "to": {
+ "pattern": "^\\S.*$",
+ "type": "string"
+ }
+ },
+ "required": [
+ "from",
+ "to",
+ "relation"
+ ],
+ "type": "object"
+ },
+ "minItems": 1,
+ "type": "array"
+ },
+ "summary": {
+ "type": "string"
+ },
+ "title": {
+ "type": "string"
+ }
+ },
+ "required": [
+ "id",
+ "title",
+ "steps"
+ ],
+ "type": "object"
+ },
+ "interplay": {
+ "properties": {
+ "boundary_groups": {
+ "items": {
+ "properties": {
+ "description": {
+ "type": "string"
+ },
+ "id": {
+ "pattern": "^\\S.*$",
+ "type": "string"
+ },
+ "label": {
+ "type": "string"
+ },
+ "members": {
+ "items": {
+ "type": "string"
+ },
+ "type": "array"
+ }
+ },
+ "required": [
+ "id",
+ "label",
+ "members"
+ ],
+ "type": "object"
+ },
+ "type": "array"
+ },
+ "clusters": {
+ "items": {
+ "properties": {
+ "id": {
+ "pattern": "^\\S.*$",
+ "type": "string"
+ },
+ "node_ids": {
+ "items": {
+ "type": "string"
+ },
+ "type": "array"
+ },
+ "owner_type": {
+ "type": [
+ "string",
+ "null"
+ ]
+ }
+ },
+ "required": [
+ "id",
+ "node_ids"
+ ],
+ "type": "object"
+ },
+ "type": "array"
+ },
+ "edges": {
+ "items": {
+ "$ref": "#/$defs/interplay_edge"
+ },
+ "type": "array"
+ },
+ "flows": {
+ "items": {
+ "$ref": "#/$defs/flow"
+ },
+ "type": "array"
+ },
+ "invariants": {
+ "items": {
+ "$ref": "#/$defs/invariant"
+ },
+ "minItems": 1,
+ "type": "array"
+ },
+ "launch": {
+ "type": "object"
+ },
+ "machines": {
+ "type": "object"
+ },
+ "nodes": {
+ "items": {
+ "$ref": "#/$defs/node"
+ },
+ "minItems": 1,
+ "type": "array"
+ },
+ "pages": {
+ "items": {
+ "properties": {
+ "components": {
+ "items": {
+ "type": "string"
+ },
+ "type": "array"
+ },
+ "id": {
+ "pattern": "^\\S.*$",
+ "type": "string"
+ },
+ "label": {
+ "type": "string"
+ },
+ "roots": {
+ "items": {
+ "type": "string"
+ },
+ "type": "array"
+ }
+ },
+ "required": [
+ "id",
+ "label"
+ ],
+ "type": "object"
+ },
+ "type": "array"
+ },
+ "triggers": {
+ "type": "array"
+ }
+ },
+ "required": [
+ "nodes",
+ "edges",
+ "flows",
+ "invariants"
+ ],
+ "type": "object"
+ },
+ "interplay_edge": {
+ "properties": {
+ "class": {
+ "enum": [
+ "structure",
+ "interplay",
+ "lifecycle",
+ "boundary",
+ "usage"
+ ],
+ "type": "string"
+ },
+ "relation": {
+ "pattern": "^\\S.*$",
+ "type": "string"
+ },
+ "source": {
+ "pattern": "^\\S.*$",
+ "type": "string"
+ },
+ "target": {
+ "pattern": "^\\S.*$",
+ "type": "string"
+ }
+ },
+ "required": [
+ "source",
+ "target",
+ "relation",
+ "class"
+ ],
+ "type": "object"
+ },
+ "invariant": {
+ "properties": {
+ "checked": {
+ "minimum": 0,
+ "type": "integer"
+ },
+ "id": {
+ "pattern": "^\\S.*$",
+ "type": "string"
+ },
+ "kind": {
+ "pattern": "^\\S.*$",
+ "type": "string"
+ },
+ "status": {
+ "enum": [
+ "holds",
+ "violated",
+ "unchecked"
+ ],
+ "type": "string"
+ },
+ "why": {
+ "type": "string"
+ }
+ },
+ "required": [
+ "id",
+ "kind",
+ "status",
+ "why"
+ ],
+ "type": "object"
+ },
+ "node": {
+ "properties": {
+ "cluster": {
+ "type": "string"
+ },
+ "component": {
+ "type": [
+ "string",
+ "null"
+ ]
+ },
+ "evidence": {
+ "items": {
+ "$ref": "#/$defs/evidence"
+ },
+ "type": "array"
+ },
+ "history_key": {
+ "type": "string"
+ },
+ "id": {
+ "pattern": "^\\S.*$",
+ "type": "string"
+ },
+ "kind": {
+ "pattern": "^\\S.*$",
+ "type": "string"
+ },
+ "label": {
+ "type": "string"
+ },
+ "line": {
+ "minimum": 1,
+ "type": "integer"
+ },
+ "owner_type": {
+ "type": [
+ "string",
+ "null"
+ ]
+ },
+ "page": {
+ "type": [
+ "string",
+ "null"
+ ]
+ },
+ "path": {
+ "type": "string"
+ },
+ "sub_kind": {
+ "type": [
+ "string",
+ "null"
+ ]
+ }
+ },
+ "required": [
+ "id",
+ "kind",
+ "label"
+ ],
+ "type": "object"
+ },
+ "store": {
+ "properties": {
+ "component": {
+ "type": [
+ "string",
+ "null"
+ ]
+ },
+ "evidence": {
+ "$ref": "#/$defs/evidence"
+ },
+ "id": {
+ "pattern": "^\\S.*$",
+ "type": "string"
+ },
+ "kind": {
+ "type": "string"
+ },
+ "label": {
+ "type": "string"
+ },
+ "persistence": {
+ "type": "array"
+ }
+ },
+ "required": [
+ "id",
+ "label",
+ "kind"
+ ],
+ "type": "object"
+ }
+ },
+ "$id": "https://hermes.dev/contracts/hermes.architecture/v1",
+ "$schema": "https://json-schema.org/draft/2020-12/schema",
+ "properties": {
+ "behavior": {
+ "type": "object"
+ },
+ "ci": {
+ "$ref": "#/$defs/ci"
+ },
+ "components": {
+ "items": {
+ "$ref": "#/$defs/component"
+ },
+ "minItems": 1,
+ "type": "array"
+ },
+ "description": {
+ "type": "string"
+ },
+ "edges": {
+ "items": {
+ "properties": {
+ "authority": {
+ "type": "string"
+ },
+ "source": {
+ "pattern": "^\\S.*$",
+ "type": "string"
+ },
+ "target": {
+ "pattern": "^\\S.*$",
+ "type": "string"
+ },
+ "type": {
+ "type": "string"
+ }
+ },
+ "required": [
+ "source",
+ "target",
+ "type"
+ ],
+ "type": "object"
+ },
+ "type": "array"
+ },
+ "evidence_metadata": {
+ "properties": {
+ "class": {
+ "type": "string"
+ },
+ "limitations": {
+ "items": {
+ "type": "string"
+ },
+ "type": "array"
+ },
+ "rules": {
+ "type": "object"
+ }
+ },
+ "required": [
+ "class",
+ "rules",
+ "limitations"
+ ],
+ "type": "object"
+ },
+ "externals": {
+ "properties": {
+ "edges": {
+ "type": "array"
+ },
+ "groups": {
+ "items": {
+ "properties": {
+ "id": {
+ "pattern": "^\\S.*$",
+ "type": "string"
+ },
+ "label": {
+ "type": "string"
+ }
+ },
+ "required": [
+ "id",
+ "label"
+ ],
+ "type": "object"
+ },
+ "type": "array"
+ },
+ "systems": {
+ "items": {
+ "$ref": "#/$defs/external"
+ },
+ "type": "array"
+ }
+ },
+ "required": [
+ "systems"
+ ],
+ "type": "object"
+ },
+ "extraction": {
+ "$ref": "#/$defs/extraction"
+ },
+ "interplay": {
+ "$ref": "#/$defs/interplay"
+ },
+ "inventory": {
+ "properties": {
+ "declarations": {
+ "minimum": 0,
+ "type": "integer"
+ },
+ "files": {
+ "minimum": 0,
+ "type": "integer"
+ },
+ "lines": {
+ "minimum": 0,
+ "type": "integer"
+ }
+ },
+ "required": [
+ "files",
+ "lines",
+ "declarations"
+ ],
+ "type": "object"
+ },
+ "layers": {
+ "items": {
+ "properties": {
+ "id": {
+ "pattern": "^\\S.*$",
+ "type": "string"
+ },
+ "label": {
+ "type": "string"
+ },
+ "order": {
+ "type": "integer"
+ }
+ },
+ "required": [
+ "id",
+ "label",
+ "order"
+ ],
+ "type": "object"
+ },
+ "type": "array"
+ },
+ "repository": {
+ "type": [
+ "string",
+ "null"
+ ]
+ },
+ "schema_version": {
+ "pattern": "^(\\d+)\\.(\\d+)\\.(\\d+)$",
+ "type": "string"
+ },
+ "source_tree_sha256": {
+ "pattern": "^[0-9a-f]{64}$",
+ "type": "string"
+ },
+ "stores": {
+ "properties": {
+ "count": {
+ "minimum": 0,
+ "type": "integer"
+ },
+ "items": {
+ "items": {
+ "$ref": "#/$defs/store"
+ },
+ "type": "array"
+ }
+ },
+ "required": [
+ "items"
+ ],
+ "type": "object"
+ },
+ "title": {
+ "type": "string"
+ }
+ },
+ "required": [
+ "schema_version",
+ "title",
+ "description",
+ "source_tree_sha256",
+ "components",
+ "interplay",
+ "extraction",
+ "ci",
+ "inventory",
+ "evidence_metadata"
+ ],
+ "title": "hermes.architecture document v1.0",
+ "type": "object"
+}
diff --git hermes-agent/docs/api/architecture.md harness/docs/api/architecture.md
new file mode 100644
index 0000000000000000000000000000000000000000..4cad5242fecb9231f3a6ea733622c45ea03495ad
--- /dev/null
+++ harness/docs/api/architecture.md
@@ -0,0 +1,473 @@
+# `architecture.*` — per-service architecture models
+
+A service that conforms to the architecture standard ships a compiler that emits an
+**architecture model** — components, the system map with its invariants, data stores,
+external systems and the CI plane (`architecture/model/model.json` in Portal is the
+reference shape) — and a `--check` that fails when the committed model drifts from the
+tree. Harness learns about such a service from a **manifest**, reads and snapshots its
+model per revision, runs its check on demand, and hands all of it to Portal, which opens
+the model from the service node on the dataflow graph. A checkout that is never pushed
+and a GitHub repository are served by the same methods and are indistinguishable to the
+client.
+
+## Manifest
+
+One JSON file per service under `~/.hermes/services/architecture/<id>.json`. The file
+stem is the id (`^[a-z0-9][a-z0-9._-]{0,63}$`); the service appears on the graph as
+`arch:<id>`.
+
+```jsonc
+{
+ "name": "Portal", // required — display name
+ "description": "Native macOS/iOS client for …", // required — markdown detail card
+ "root": "/Users/me/Desktop/portal", // local checkout (never has to be pushed)
+ "repository": "owner/name", "ref": "main", // …or a GitHub repository at a ref
+ "model": "architecture/model/model.json", // default; relative, inside the service
+ "check": ["python3", "scripts/build_architecture.py", "--check"], // local only
+ "source_files": ["scripts/build_architecture.py"], // extra code shown on the node
+ "inputs": [], "outputs": [], "side_effects": [], "relationships": [] // dataflow, as launchd sidecars
+}
+```
+
+`root` or `repository` is required. A local service's revision is its git head (or a
+content digest of the model when there is no repository); a GitHub service's revision is
+the model's own `source_revision`, falling back to the ref. Malformed manifests are
+logged and skipped, never fatal.
+
+### Standalone or bound to a runtime service
+
+A manifest describes a codebase. When nothing else on the gateway runs that codebase
+(Portal, a library, a tool), the manifest is **standalone** and the graph draws it as its
+own `arch:<id>` service node. When a process, Docker, Nomad or launchd provider already
+reports the running service, the manifest **binds** to it and annotates that node instead
+of adding a second one:
+
+```jsonc
+{
+ "name": "Hermes Gateway",
+ "description": "Hermes gateway architecture",
+ "root": "/Users/me/.hermes/hermes-agent",
+ "check": ["python3", "scripts/build_architecture.py", "--check"],
+ "runtime": {"provider": "launchd", "id": "ai.hermes.gateway"}
+}
+```
+
+The binding is typed and exact — never a display-name match. `runtime.id` is the
+provider's own identity and resolves to the canonical graph id the provider emits:
+
+| `runtime.provider` | `runtime.id` | Graph node |
+|---|---|---|
+| `launchd` | the launchd label | `launchd:<label>` |
+| `docker` | the container id | `docker:<first 12 chars>` |
+| `nomad` | the job id | `nomad:<job>` |
+| `process` | the tracked process id | `proc_<id>` |
+
+A binding with an unknown provider, a blank or non-string id, a prefixed id, or an
+`arch:` id makes the manifest invalid (logged, skipped). Omit `runtime` when a standalone
+codebase node is intended.
+
+**Merge authority** for a bound manifest, applied in `tools/service_graph.py` after every
+provider has reported and before the graph is built:
+
+| Fact | Owner |
+|---|---|
+| graph node id, health/liveness, description, label | the runtime provider |
+| inputs, outputs, side effects, relationships (topology) | the runtime provider — the manifest's dataflow is not drawn |
+| `architecture` annotation | the manifest (`ref` is `arch:<manifest-id>`, plus `runtime`: the graph id) |
+| `source_files` | deterministic union of both, deduplicated by normalized path |
+| browse root | `arch-<manifest-id>` → the manifest's `root`, as for a standalone manifest |
+
+If the bound runtime service is **absent** (not running, not reported), nothing is drawn
+for the manifest — no `arch:` node is fabricated — and a warning names the target. The
+model stays reachable through `architecture.describe`. If **two manifests bind one
+runtime service**, neither is applied (a warning names both); there is no last-writer-wins.
+
+The **RPC identity and the graph identity differ** for a bound manifest: `architecture.*`
+methods take `arch:<manifest-id>` (or the bare id), while the node on `cron.graph` is the
+runtime's id and carries `architecture.ref` pointing back at the manifest.
+
+### Deployments: where the code runs off this machine
+
+The four runtime providers see services on the gateway host. A Lambda, a Cloud Run
+revision, an ECS service or a Fly app has no process, port or container here, so a
+manifest may declare **deployments**: one per environment, each with the provider's own
+identity, an explicit health probe, an optional revision probe and its own log sinks.
+Probes are the deployment's declaration of how to ask — an HTTPS GET with an expected
+status, or a bounded shell-less command whose exit code answers — never a provider SDK
+the gateway has to carry. Only declared URLs and argv are ever contacted or run.
+
+```jsonc
+"deployments": [
+ {
+ "id": "prod", "environment": "production", "provider": "aws-lambda",
+ "target": "arn:aws:lambda:us-east-1:123456789012:function:demo",
+ "url": "https://demo.example.com", // optional; drawn as an output
+ "health": {"kind": "https", "url": "https://demo.example.com/healthz", "expect": [200, 204], "timeout_s": 5},
+ "revision": {"kind": "command", "argv": ["aws", "lambda", "get-function-configuration", "--function-name", "demo", "--query", "Version", "--output", "text"]},
+ "logs": [{"id": "cloudwatch", "kind": "command", "argv": ["aws", "logs", "tail", "/aws/lambda/demo", "--since", "15m", "--format", "short"]}]
+ },
+ {
+ "id": "staging", "provider": "cloud-run", "target": "projects/p/locations/us/services/demo",
+ "health": {"kind": "command", "argv": ["gcloud", "run", "services", "describe", "demo", "--region", "us", "--format", "value(status.conditions[0].status)"]},
+ "revision": {"kind": "https", "url": "https://staging.demo.example.com/version", "json_path": "build.sha"}
+ }
+]
+```
+
+| Field | Meaning |
+|---|---|
+| `id` | unique per manifest, `^[a-z0-9][a-z0-9._-]{0,63}$`; the node is `deploy:<manifest-id>/<id>` |
+| `environment` | display label; defaults to `id` |
+| `provider` | a lowercase token (`aws-lambda`, `ecs`, `cloud-run`, `fly`, `vercel`, `kubernetes`, …); informational |
+| `target` | the provider's own identity for the deployment |
+| `health` | required. `https`: GET `url`, live when the status is in `expect` (default `200`). `command`: run `argv` without a shell, live on exit 0. `timeout_s` defaults to 5, max 60 |
+| `revision` | optional. `command`: the first non-empty stdout line. `https`: the body, or `json_path` (dotted) into a JSON body |
+| `logs` | sinks of kind `command` only (see *Log capture*); read once per `service.logs` call, never followed |
+
+Each deployment is a **service node of its own** on the dataflow graph (`deploy:<id>/<env>`),
+labelled `<Name> · <environment>`, with `health` in the same shape the Docker provider
+reports (`status` live / down / unknown, `probe`, `target`, `checked_at`, `latency_ms`,
+`message`), a `deploys` relationship to the codebase node `arch:<id>`, and the manifest's
+`architecture` annotation plus `deployment`. Staging and production are two nodes with two
+healths. Probe results are cached in memory for 30 seconds; the graph and
+`architecture.describe` read the last known result (probing once when nothing is known),
+and `service.deployments.probe` runs the probes now. A probe that cannot run is `unknown`
+with the reason; a probe that times out or refuses is `down`. When a deployment's revision
+probe answers with a stored revision, `architecture.history` marks that revision `live_in`
+that environment.
+
+## On the dataflow graph
+
+`cron.graph` and `code.graph` compose the four runtime providers with the manifests
+(`tools/service_graph.collect_graph_services`). A standalone manifest is a service node
+of its own; a bound manifest annotates the runtime node. Either way the node has
+`kind: "service"`, its `source_files` (the model file plus any declared files, resolved
+onto browse roots like a cron's scripts), and an `architecture` annotation:
+
+```jsonc
+"architecture": {
+ "ref": "arch:portal", "source": "local", "revision": "62911e4…",
+ "model": "architecture/model/model.json", "snapshots": 3,
+ "runtime": "launchd:ai.hermes.gateway", // bound manifests only
+ "check": {"status": "passed", "checked_at": "2026-09-24T09:00:00+00:00"},
+ "summary": {"components": 31, "nodes": 240, "invariants": {"total": 12, "holds": 12, "violated": []}, "gates": 14, …}
+}
+```
+
+Like `source_files`, the annotation is node metadata and stays outside the changeset
+commitment digest. A local service's checkout is also exposed as a read-only browse root
+named `arch-<id>` for `files.list` / `files.read`.
+
+## Compiling a Python service
+
+A Portal-style compiler is Swift-specific. Any Python service gets a conforming model from
+`tools/architecture_compile_python.py`: it reads the tree plus `architecture/config.json`,
+extracts with `ast` (declarations, entrypoints, routes, subprocess spawns, file writes,
+HTTP clients, sockets, threads and tasks, environment reads, external imports, enum-typed
+state machines, persistent stores), draws the map (modules, classes, entrypoints,
+endpoints, stores, resources, external packages) with provenance for every construction,
+wires the declared gates into one merge gate, validates the result against the
+`hermes.architecture` contract (`tui_gateway/architecture_contract.py`) and writes
+`architecture/model/model.json`. `--check` fails when the committed model drifts.
+
+```jsonc
+// <service>/architecture/config.json
+{
+ "title": "Home Awareness", "description": "Camera capture, perception and room state.",
+ "source_root": ".", "exclude": ["tests/**"],
+ "components": [
+ {"id": "capture", "label": "Capture", "description": "Frame capture and orchestration.", "patterns": ["capture/**", "main.py"]},
+ {"id": "perception", "label": "Perception", "description": "Detection and tracking.", "patterns": ["perception/**"]}
+ ],
+ "external_systems": [ // declared boundaries (Portal-shaped); each must be observed ≥ 1 time
+ {"id": "rtsp-camera", "label": "RTSP camera", "category": "camera", "protocol": "RTSP",
+ "description": "The PTZ camera frames are pulled from.", "signatures": [{"pattern": "rtsp://", "scope": "strings"}]},
+ {"id": "opencv", "label": "OpenCV", "category": "vision", "description": "On-device perception.", "signatures": ["\\bcv2\\b"]}
+ ],
+ "external_groups": [ // boundary hulls: a category belongs to one group, a group needs a member
+ {"id": "cameras", "label": "Cameras", "description": "Video sources.", "categories": ["camera"]}
+ ],
+ "declared": { // optional: a person's assertions, every reference must resolve
+ "nodes": [{"id": "declared:camera", "kind": "device", "label": "PTZ camera", "path": "capture/ptz.py", "line": 12}],
+ "edges": [{"source": "class:capture:Capture", "target": "declared:camera", "relation": "reads"}],
+ "flows": [{"id": "boot", "title": "Boot", "steps": [{"from": "class:capture:Capture", "to": "declared:camera", "relation": "reads"}]}]
+ },
+ "gates": {
+ "commands": [{"id": "check", "name": "Model is current", "command": "python3 tools/architecture_compile_python.py . --check"},
+ {"id": "tests", "name": "Unit tests", "command": "python3 -m pytest -q", "role": "gate"}],
+ "workflows": ".github/workflows" // optional: GitHub jobs join the gates
+ }
+}
+```
+
+```sh
+python3 tools/architecture_compile_python.py /path/to/service # writes architecture/model/model.json
+python3 tools/architecture_compile_python.py /path/to/service --check # exit 1 when stale or non-conforming
+```
+
+**Extrinsic dependencies** are modelled the way Portal models them. A package import
+outside the standard library is an `external` node of `sub_kind` `package`. A declared
+`external_systems` entry is an `external` node of `sub_kind` `system`: its `signatures` are
+regexes matched against comment- and string-masked code (plain strings, or
+`{"pattern", "scope": "code"}`) or against string-literal contents only
+(`"scope": "strings"`, for hostnames, URL schemes and paths); every hit is a citation under
+the mechanical pass `py.boundary.external_signature`, and a `uses` edge of class `boundary`
+runs from the citing class (or the module, for a module-level hit) to the system. A declared
+system nothing matches fails the compile. When a code-scoped signature matches an imported
+package's root name (`\bcv2\b` against `import cv2`), the system **absorbs** the package: the
+import line becomes one of the system's origins and no separate package node is drawn.
+`external_groups` become `interplay.boundary_groups` with `members` = the external nodes
+whose `category` the group lists (packages carry the category `package`). Intrinsic versus
+extrinsic is the edge `class` — `structure`, `lifecycle` and `interplay` inside the service,
+`boundary` across it — plus the boundary-group hulls. The `externals` section lists each
+declared system with `hit_count`, `file_count`, `paths` and the owning `component`.
+
+Point the service's manifest at the model (`"model": "architecture/model/model.json"`) and at
+the check (`"check": ["python3", "…/tools/architecture_compile_python.py", ".", "--check"]`).
+Every file must belong to one component and at least one gate must be declared; the
+compiler refuses to write a model that does not conform.
+
+## Compiling any service: language packs
+
+`tools/architecture_compiler` is the multi-language compiler: one language-independent core and one
+**language pack** per language on a [tree-sitter](https://tree-sitter.github.io) floor. Supported today:
+Swift (`.swift`), TypeScript/JavaScript (`.ts .tsx .js .jsx .mjs .cjs`), Go (`.go`), Rust (`.rs`) and
+Python (`.py`). A service may mix languages; every file is parsed by the pack for its extension.
+
+```
+python3 -m pip install -r tools/architecture_compiler/requirements.txt # tree-sitter + grammar bundle
+python3 -m tools.architecture_compiler <service-root> # writes architecture/model/model.json
+python3 -m tools.architecture_compiler <service-root> --check # exit 1 when the committed model is stale
+```
+
+The config is the Python compiler's `architecture/config.json` (see above) plus four keys:
+
+```json
+{
+ "external_systems": [
+ {"id": "camera", "label": "Tapo camera", "category": "cameras", "description": "RTSP feed.",
+ "signatures": [{"pattern": "rtsp://", "scope": "strings"}, "\\bcv2\\b"]}
+ ],
+ "external_groups": [{"id": "sensing", "label": "Sensing", "categories": ["cameras"]}],
+ "local_modules": ["example.com/demo"],
+ "rules": [
+ {"id": "publish", "description": "A room-state publish", "family": "boundary", "language": "python",
+ "regex": "\\bpublish_state\\(", "scope": "code",
+ "produces": {"kind": "resource", "sub_kind": "publisher", "relation": "notifies", "edge_class": "interplay"}},
+ {"id": "handlers", "description": "Every handler class", "family": "wiring", "language": "python",
+ "query": "(class_definition name: (identifier) @label) @site"}
+ ]
+}
+```
+
+- **`external_systems`** are the extrinsic dependencies a person names, observed through **signatures**:
+ regexes matched against comment-masked code (`scope: code`, the default) or against string-literal
+ contents only (`scope: strings`, for hostnames and URL schemes). A declared system with **zero hits fails
+ the compile**. Each system becomes an `external:<id>` node wired by `uses` (class `boundary`) from every
+ type or module that cites it, and a row in `externals.systems` with hit and file counts. A signature that
+ matches an imported package's root **absorbs** that package: no separate `external:<package>` node is
+ drawn for it. Packages no system claims still appear, uncategorised, so nothing is hidden.
+- **`external_groups`** put categories into boundary hulls (`interplay.boundary_groups`), the way Portal draws
+ *Platform storage* and *On-device inference*. A group with no members, or a category claimed by two groups,
+ fails the compile.
+- **`local_modules`** lists import prefixes that belong to the service itself (a Go module path, a Rust
+ crate, an internal npm scope) so they never count as external.
+- **`rules`** add project-specific passes on top of the pack's baseline. A rule is a regex (`scope`
+ `code` | `raw` | `strings`) or a tree-sitter `query` whose `@site` capture is the citation and optional
+ `@label` the label. `produces` puts a construction on the map (`external`, `store`, `resource`,
+ `endpoint`) with the relation and edge class the owner is wired by; without it the rule only cites,
+ which still maps the enclosing declaration. Rule ids are namespaced by language (`python.publish`).
+- **`languages`** (optional) restricts which packs run.
+
+Every pack provides the same baseline passes where the concept exists — `<lang>.type`, `<lang>.entrypoint`,
+`<lang>.import_external`, `<lang>.route`, `<lang>.http_client`, `<lang>.socket_or_server`,
+`<lang>.file_write`, `<lang>.process_spawn`, `<lang>.env_read`, `<lang>.persistent_store`,
+`<lang>.concurrency`, `<lang>.state_machine` — and Swift adds Portal's own conventions:
+`swift.store_declaration` (`*Store/*Cache/*Inventory/*Ledger` types become store nodes), `swift.ui_trigger`
+(a SwiftUI action or lifecycle closure calling a same-type property's method draws `drives`) and
+`swift.rpc_call` (`call("namespace.method")` draws an endpoint the caller `invokes`). Intrinsic versus
+extrinsic is expressed exactly as Portal expresses it: edge `class` (`structure`/`lifecycle`/`interplay`
+inside, `boundary` across) plus the boundary hulls.
+
+Adding a pack means one module under `tools/architecture_compiler/packs/`: the grammar name, the comment and
+string node types (so signatures can be scoped), a declaration census, an import reader, an entrypoint
+finder and the rule table; register it in `packs/__init__.py`. The compiler validates its output against
+the contract and refuses to write a non-conforming model; two compiles of one tree are identical bytes.
+
+What the passes cannot see, stated in every model's `evidence_metadata.limitations`: dynamic dispatch,
+reflection and plugin registries, routes assembled at runtime, decorators built at runtime, macro and
+derive expansions, and any mechanism reached through a wrapper in another file. Portal keeps its own
+Swift compiler until the Swift pack plus a project rule table reproduces its map.
+
+## Methods
+
+| Method | Params | Returns |
+|---|---|---|
+| `architecture.list` | — | `{services: [{id, label, description, source, root, repository, ref, model, check_configured, runtime, status}], contract: {name, version}}` — `status` is the node annotation above (with `contract` and `conforming`); `runtime` is the binding (`{provider, id, graph_id}`) or null |
+| `architecture.describe` | `service` (graph id or bare id), `revision?` | `{service: {…}, revision, source, stored_at, summary, check, contract, model}` — without `revision` the current model is read now, validated against the contract and snapshotted; with it a stored snapshot is returned. **4032** model missing/invalid/unfetchable, **4033** does not conform to the contract (message names the problems), **4404** no such stored revision |
+| `architecture.check` | `service` | `{service, check: {status: passed\|failed\|unavailable, exit_code?, output?, reason?, revision, checked_at, duration_s, command}}` — runs the manifest's `check` in `root`, bounded at 300 s. A GitHub service or a manifest without `check` is `unavailable` with a `reason` |
+| `architecture.history` | `service` | `{service, source, latest, head, revisions: [{revision, source, stored_at, summary, contract, commit?, commits_since_previous?, deployed, deployed_at?, live_in?}], runtime?, checks: [runs, newest first]}` — see *Revision history*; `live_in` lists the deployments whose last revision probe answered with that revision |
+| `service.deployments` | `service` | `{service, deployments: [{id, graph_id, environment, provider, target, url, health_probe, revision_probe, logs, health?, revision?, probed_at?}]}` — the declarations with the last known probe, without probing |
+| `service.deployments.probe` | `service`, `deployment?` | the same shape, after running the declared health and revision probes now (**4050** unknown deployment) |
+| `architecture.diff` | `service`, `from?`, `to?` | `{service, from, to, nodes: {added, removed}, edges: {added, removed}, invariants: {added, removed, changed}, files: {added, removed, changed}, gates: {jobs_added, jobs_removed, ratchets_added, ratchets_removed}, summary: {from, to}, git?}` — `to` defaults to the latest snapshot, `from` to the one before it. **4404** a revision is not stored (or nothing precedes `to`), **4001** a malformed revision |
+
+Common errors: **4029** missing `service`, **4030** unknown service; **5040–5044**
+internal, per method. All five run on the RPC pool (`_LONG_HANDLERS`). Reading a service's
+logs is `service.logs` — see [service-logs.md](service-logs.md).
+
+`summary` is derived from the model without the client loading it: schema version,
+component/file/line counts, map nodes/edges/flows, invariants with the violated ids,
+store and external counts, and the CI plane's gate/ratchet/workflow counts.
+
+## Contract
+
+Every model the gateway reads is validated against **`hermes.architecture` v1.0**
+(`tui_gateway/architecture_contract.py`; JSON Schema export in
+`docs/api/architecture-document-v1.schema.json`, digest `b89978fcf4c8fed4f4f90a516c971d9c8950522040342ee853f64db3e2686541`).
+The module is the contract between a service's compiler, this gateway and every
+renderer; it is vendored **byte-for-byte** into each consumer and pinned by digest there
+(Portal: `architecture/contract/pins.json`), so a contract change lands in every
+repository in lock-step rather than as a drift one side discovers at decode time.
+
+**Required sections** — a service either proves where its map came from and what defends
+it, or it is not a conforming service:
+
+| Section | What it must carry |
+|---|---|
+| `components` | ≥1 component: `id`, `label`, `description`, `files`, `declarations`, counts |
+| `interplay` | the system map: `nodes` (≥1), `edges` (endpoints are nodes), `flows` (steps end on nodes by `history_key`/`id` or `page:<id>`), `invariants` (≥1; status `holds`/`violated`/`unchecked`) |
+| `extraction` | where the map came from: `files` (a file is `touched` iff `citations > 0`), `passes` (≥1 `mechanical`), `entities` **one per node** with ≥1 origin `(path, line, rule, family)` — origins name analysed files and declared passes |
+| `ci` | the gates: `workflows` (≥1), `jobs` (≥1; role `gate`/`post-merge`/`manual`/`disabled`/`local`), `edges` between jobs, triggers and the merge, `merge` with ≥1 job as input, `ratchets`, `static_checks`, `summary` |
+| `inventory` | `files`, `lines`, `declarations` |
+| `evidence_metadata` | `class`, `rules`, `limitations` |
+
+`stores`, `externals`, `layers`, `edges` and `behavior` are optional. Top-level `title`,
+`description`, `source_tree_sha256` (64 hex) and semver `schema_version` are required.
+
+**Versioning.** `schema_version`'s major is the contract major: this gateway speaks
+`1.x` and refuses any other major. A minor adds optional fields or
+sections; unknown fields are ignored everywhere. Unknown enum values are rejected only
+where renderers branch on them (edge `class`, invariant `status`, pass `class`, job
+`role`, extraction `authority`). Identifiers must be unique and every reference must
+resolve (edges → nodes, entities ↔ nodes, origins → files and passes, `needs`/merge
+inputs/ratchets/static checks → jobs).
+
+**Enforcement.** Validation runs on every read, local or GitHub, before a snapshot is
+stored, so a stored revision is always a conforming one. A non-conforming document is
+refused with **4033** whose message names the contract, the first five problems and how
+many more (`model at … does not conform to hermes.architecture v1.0: …; … (+N more)`);
+Portal shows it verbatim. `architecture.describe` and `architecture.history` entries carry
+`contract: {name, version, major, minor, required_sections, optional_sections, schema_digest}`;
+the node annotation (`architecture.list` → `status`) carries `contract: {name, version}` and
+`conforming: bool` (local: the checkout's model is read and validated; GitHub: conforming once
+a snapshot exists, otherwise `problem` says the model has not been read yet).
+`gateway.capabilities` advertises `architecture: {methods, contract}` beside the flat
+`capability_names` list.
+
+## Log capture
+
+Log capture is part of the standard for **local** services (manifests with a `root`):
+the manifest declares where the service's logs land, and a local service that declares
+no resolvable sink is **not conforming** (`status.conforming: false`,
+`problem: "no log capture declared: add a logs sink to the manifest"` — joined with the
+contract problem when the model fails too). GitHub-only manifests are exempt: logs are a
+runtime property and the runtime is not here; a `logs` block on one is ignored with a warning.
+
+```jsonc
+"logs": [
+ {"id": "app", "kind": "file", "path": "~/Library/Logs/Portal/portal.log", "label": "Application"},
+ {"id": "runs", "kind": "directory", "path": "~/.hermes/services/demo/logs"}, // newest file by mtime
+ {"id": "out", "kind": "launchd_stdout"}, // from the bound job's plist
+ {"id": "err", "kind": "launchd_stderr", "path": "/var/log/demo.err"} // explicit path wins
+]
+```
+
+Kinds: `file`, `directory` (the newest regular file by mtime is the active file), `command`
+(a deployment's bounded, shell-less command whose stdout is the tail — valid only under a
+deployment's `logs`, read once per request, never followed),
+`launchd_stdout` / `launchd_stderr` (path derived from the bound launchd job's
+`StandardOutPath` / `StandardErrorPath` — `~/Library/LaunchAgents`, then
+`/Library/LaunchAgents`, `/Library/LaunchDaemons` — when `path` is omitted; these kinds need a
+`runtime` binding with provider `launchd`). Ids are unique, paths absolute (`~` allowed),
+unknown kinds fail closed. A launchd sink whose plist cannot be read keeps the manifest valid
+and records a `problem`; the service is then reported non-conforming rather than vanishing.
+`architecture.describe` (the `service.logs` field) and `architecture.list` (`logs`) carry every sink
+resolved at call time: `exists`, `size_bytes`, `modified_at` (a missing file is
+`exists: false`, never an error); the node annotation carries the sink ids (`status.logs`).
+
+Reading and following the sinks is the `service.*` namespace (`service.logs`,
+`service.logs.follow`, event `service.log`), keyed by graph service id, so a launchd node's
+plist-derived stdout/stderr and a manifest's declared sinks resolve through one method — see
+[service-logs.md](service-logs.md).
+
+## Revision history
+
+`architecture.history` walks the stored snapshots (genesis first, newest last) and, for a
+**local root**, joins each to git:
+
+- `commit` — `{sha, author, date, subject}` of the snapshot's revision (`git log -1`); absent
+ for a `working-tree` or `sha256:` revision, or when git fails.
+- `commits_since_previous` — the commits `previous..revision` between the prior snapshot and
+ this one, oldest first, at most 50.
+- `deployed` / `deployed_at` — the newest snapshot whose revision equals the checkout's
+ current `HEAD` (`head` is also returned). **This means "the revision the checkout is at
+ now", not proof that a process restarted.** When the manifest binds a runtime service,
+ `runtime: {provider, graph_id, pid?}` carries what the provider can say: launchd reports
+ the running pid when `launchctl print` shows one; no provider reports a start time, so
+ none is invented.
+
+`architecture.diff` compares two stored snapshots by stable identity, so a rename is not
+churn: nodes by `history_key` (falling back to `id`), edges by `(source key, target key,
+relation)`, invariants by id (with status flips under `changed`), extraction files by path
+(with `lines_from`/`lines_to` when the line count moved), CI jobs and ratchets by id.
+`summary.from`/`summary.to` are the two revisions' summaries. For a local root whose two
+revisions are git commits, `git` adds `commits` (oldest first, at most 50) and `stat`
+(`git diff --numstat`, at most 500 paths, binary files as null counts) with `truncated`
+when either bound was hit. `architecture.describe` reports `is_latest` so a client viewing
+an older revision can say so.
+
+## Snapshots and checks
+
+Every revision read is stored under `~/.hermes/architecture/<id>/<revision>.json` with
+`index.json` (latest, revisions with summaries). At most 30 snapshots are kept per
+service; pruning removes the oldest **after the first**, so genesis is never lost. Check
+runs land in `checks.json` (20 newest).
+
+## Event
+
+`architecture.changed` — session-less, broadcast to every client (the log follow stream is
+`service.log`, see [service-logs.md](service-logs.md)):
+
+```jsonc
+{"service": "arch:portal", "revision": "62911e4…", "source": "local", "reason": "snapshot"}
+{"service": "arch:portal", "revision": "62911e4…", "source": "local", "reason": "check", "status": "failed"}
+```
+
+Emitted when `architecture.describe` stores a revision it had not seen and when
+`architecture.check` finishes. Clients refetch via `architecture.describe`.
+
+## Capabilities
+
+`architecture.list`, `architecture.describe`, `architecture.check`, `architecture.history`,
+`architecture.diff` are advertised by `gateway.capabilities` in `capability_names`, and
+`architecture: {methods, events, contract}` names the methods, the event
+(`architecture.changed`) and the contract (see above) so a client can decode a served
+document knowing its major before the first call. The log methods are advertised under
+`service: {methods, events}`.
+
+## Security
+
+Manifests are operator-owned state under `HERMES_HOME`. Model paths are resolved inside
+the declared root and rejected when they escape it; models are capped at 16 MiB and must
+be JSON objects with a `schema_version` that conform to the contract. Check commands run only for local services, in
+the declared root, with output truncated to 4 000 characters. Log reads (`service.logs`) open only the
+paths the manifest declares or the bound launchd plist names, scan at most 4 MiB, and return
+at most 2 000 lines. GitHub fetches go to
+`raw.githubusercontent.com` over HTTPS and send `GITHUB_TOKEN`/`GH_TOKEN` when set.
+
+Implementation: `tui_gateway/architecture_contract.py` (the contract), `tui_gateway/architecture_store.py`
+(manifests, bindings, validation, snapshots, checks), `tools/architecture_services.py` (definitions),
+`tools/service_graph.py` (runtime providers + composition), `tui_gateway/methods_architecture.py`
+(handlers); tests in `tests/gateway/test_architecture_contract.py`, `tests/gateway/test_architecture_store.py`,
+`tests/gateway/test_methods_architecture.py`, `tests/cron/test_architecture_services.py`,
+`tests/cron/test_architecture_binding.py` (fixture: `tests/gateway/architecture_fixtures.py`).
diff --git hermes-agent/docs/api/service-logs.md harness/docs/api/service-logs.md
new file mode 100644
index 0000000000000000000000000000000000000000..2d1aa5ff46f7a19fc82aa965caccb0efa4aa1a14
--- /dev/null
+++ harness/docs/api/service-logs.md
@@ -0,0 +1,86 @@
+# Service logs — `service.logs`, `service.logs.follow`, event `service.log`
+
+Logs are a property of the **running** service, not of its architecture, so they live in
+the `service.*` namespace and are keyed by the **graph service id** the cron dataflow graph
+uses: `arch:<id>` (an architecture manifest), `launchd:<label>`, `docker:<12>`,
+`nomad:<job>`, `proc_<id>`. Enforcement lives with the architecture manifest: a local
+service must declare log sinks or it is non-conforming — see
+[architecture.md → Log capture](architecture.md#log-capture) for the manifest shape.
+
+## Sink resolution by provider
+
+| Service id | Sinks |
+|---|---|
+| `arch:<id>` | The manifest's declared sinks. When the manifest binds a launchd runtime, the plist's `StandardOutPath` / `StandardErrorPath` are added as `launchd_stdout` / `launchd_stderr` unless a declared sink already has that id or that (kind, path) |
+| `launchd:<label>` | The plist's paths as `stdout` / `stderr` (kinds `launchd_stdout` / `launchd_stderr`); when a manifest binds this label, its declared sinks are unioned in. A label with no plist and no manifest has no sinks (4040) |
+| `docker:*`, `nomad:*`, `proc_*` | **4042** `log capture is not implemented for this provider yet` — an honest error, never a fake empty list |
+
+Anything else is **4001** (not a graph service id); an unknown `arch:` id is **4030**.
+Plists are looked up in `~/Library/LaunchAgents`, then `/Library/LaunchAgents`,
+`/Library/LaunchDaemons`.
+
+## Methods
+
+| Method | Params | Returns |
+|---|---|---|
+| `service.logs` | `service`, `sink?` (default: the first sink), `lines?` (default 200, max 2000), `cursor?` | `{service, sink: {id, kind, label, path, exists, size_bytes, modified_at}, sinks: [...all resolved...], lines: [str], cursor, truncated, rotated?, encoding: "utf-8-replace"}` |
+| `service.logs.follow` | `service`, `sink?`, `enabled` (default true), `cursor?` | started/refreshed: `{service, following: true, sink, cursor}`; stopped: `{service, following: false, sink, stopped: bool}` |
+
+Errors: **4029** missing `service`; **4001** bad params or not a graph id; **4030** unknown
+`arch:` service; **4040** unknown sink id, or the service has no sinks; **4041** the sink has
+no file yet; **4042** provider without log capture; **5044/5045** internal. Both run on the
+RPC pool (`_LONG_HANDLERS`).
+
+### Reads are bounded and never leave the resolved sinks
+
+Without a `cursor`, `service.logs` returns the last `lines` **complete** lines, scanning at
+most 4 MiB from the end of the active file, and `cursor` — the byte offset just after the
+last complete line — to continue from. With a cursor it returns every complete line appended
+since (bounded by `lines`; `truncated: true` when more remain, and the returned cursor resumes
+exactly where the page ended). A file shorter than the cursor was rotated or truncated: the
+read restarts from the tail with `rotated: true`. Bytes decode as UTF-8 with replacement;
+a partial trailing line is never returned until its newline arrives. For a `directory` sink,
+`sink.path` is the active file (newest by mtime). A caller names a sink by **id**; a path
+where an id is expected is simply an unknown sink (4040).
+
+### Follow
+
+`service.logs.follow {enabled: true}` starts a daemon thread that polls the sink every
+second and broadcasts the session-less event `service.log`:
+
+```jsonc
+{"service": "arch:demo", "sink": "app", "lines": ["…", "…"], "cursor": "18342"}
+{"service": "launchd:com.example.cam", "sink": "stdout", "lines": ["fresh"], "cursor": "6", "rotated": true}
+{"service": "arch:demo", "sink": "app", "lines": [], "cursor": "18342", "stopped": "idle-timeout"}
+```
+
+Events are coalesced (at most 500 lines each) and sent only when complete new lines exist.
+One follower per `(service, sink)`: asking again refreshes its idle clock and returns the
+same cursor. It stops on `{enabled: false}` or after ten minutes without a client asking
+again; the final event carries `stopped` (`"stopped"` or `"idle-timeout"`). Followers are
+daemon threads; they are not persisted across restarts and there is no explicit shutdown
+hook — process exit ends them (the same posture as the wiki watcher).
+
+## Capabilities
+
+`gateway.capabilities` advertises `service: {methods: ["service.logs", "service.logs.follow"],
+events: ["service.log"]}` and lists both methods in `capability_names`.
+
+## Limitations
+
+- Docker, Nomad and bare-process services return 4042; their log capture is not implemented.
+- The cron graph node annotation does not yet carry sink ids for launchd nodes; a client
+ resolves them by calling `service.logs` (the `sinks` array) for the node's id.
+- A launchd plist that names no `StandardOutPath`/`StandardErrorPath` yields no derived sinks.
+
+## Deployments and command sinks
+
+A deployment declared on a manifest (see [architecture.md](architecture.md), *Deployments*)
+has the graph id `deploy:<manifest-id>/<deployment-id>` and resolves to that deployment's own
+sinks. Those are of kind `command`: a bounded, shell-less command whose stdout *is* the log
+tail (`aws logs tail`, `gcloud logging read`, `flyctl logs`). `service.logs` runs it once
+(30 s, 4 MiB cap) and returns the last `lines` lines; the result has `cursor: null`,
+`exit_code` and `truncated`. A missing executable, a timeout or a failing command with no
+output is **4041** with the reason. `service.logs.follow` on a command sink is **4042**:
+there is nothing to append to, so poll `service.logs`. An unknown deployment is **4050**.
+
diff --git hermes-agent/tests/cron/test_architecture_binding.py harness/tests/cron/test_architecture_binding.py
new file mode 100644
index 0000000000000000000000000000000000000000..bf9a16b420ac29412ee0c946e6feb88bc5a371e8
--- /dev/null
+++ harness/tests/cron/test_architecture_binding.py
@@ -0,0 +1,263 @@
+"""Architecture manifests bound to runtime services annotate the runtime node;
+standalone manifests keep their own node (tools/service_graph.py)."""
+import json
+import logging
+
+import pytest
+
+from cron.changesets import configuration_digest
+from cron.jobs import build_cron_graph
+from tools import service_graph
+from tools.architecture_services import collect_architecture_definitions, collect_architecture_services
+from tests.gateway.architecture_fixtures import log_sink, minimal_document
+from tui_gateway import architecture_store as store
+from tui_gateway import files_browse
+
+
+@pytest.fixture
+def home(tmp_path, monkeypatch):
+ root = tmp_path / ".hermes"
+ monkeypatch.setenv("HERMES_HOME", str(root))
+ return root
+
+
+def _write_manifest(tmp_path, stem, runtime=None, **extra):
+ root = tmp_path / stem
+ (root / "architecture" / "model").mkdir(parents=True, exist_ok=True)
+ (root / "scripts").mkdir(exist_ok=True)
+ (root / "scripts" / "build.py").write_text("print('hi')\n", encoding="utf-8")
+ (root / "architecture" / "model" / "model.json").write_text(json.dumps(minimal_document()), encoding="utf-8")
+ manifest = {"name": stem.title(), "description": f"The {stem} codebase.", "root": str(root), "logs": [log_sink(root)],
+ "source_files": ["scripts/build.py"], "outputs": ["https:127.0.0.1:7000"]}
+ if runtime is not None:
+ manifest["runtime"] = runtime
+ manifest.update(extra)
+ store.manifests_dir().mkdir(parents=True, exist_ok=True)
+ (store.manifests_dir() / f"{stem}.json").write_text(json.dumps(manifest), encoding="utf-8")
+ return root
+
+
+def _runtime(service_id, **extra):
+ service = {
+ "id": service_id, "label": "Demo runtime", "description": "Runs the demo.",
+ "inputs": ["file:~/.hermes/config.yaml"], "outputs": ["https:127.0.0.1:9000"], "side_effects": ["notify:ops"],
+ "source_files": ["/opt/demo/serve.py"],
+ "health": {"status": "healthy", "probe": "http", "target": "http://127.0.0.1:9000/health", "checked_at": "t", "latency_ms": 3, "message": ""},
+ }
+ service.update(extra)
+ return service
+
+
+# ── Binding validation ───────────────────────────────────────────────────────
+
+
+def test_runtime_binding_resolves_each_provider_to_its_canonical_graph_id():
+ assert store.normalize_runtime_binding({"provider": "launchd", "id": "ai.hermes.gateway"})["graph_id"] == "launchd:ai.hermes.gateway"
+ assert store.normalize_runtime_binding({"provider": "docker", "id": "0123456789abcdef0123"})["graph_id"] == "docker:0123456789ab"
+ assert store.normalize_runtime_binding({"provider": "nomad", "id": "dashboard"})["graph_id"] == "nomad:dashboard"
+ assert store.normalize_runtime_binding({"provider": "process", "id": "proc_0123456789ab"})["graph_id"] == "proc_0123456789ab"
+ assert store.normalize_runtime_binding({"provider": "process", "id": "0123456789ab"})["graph_id"] == "proc_0123456789ab"
+ for bad, reason in (
+ ({"provider": "kubernetes", "id": "x"}, "provider must be one of"),
+ ({"provider": "launchd", "id": ""}, "non-empty"),
+ ({"provider": "launchd", "id": " "}, "non-empty"),
+ ({"provider": "launchd", "id": 7}, "non-empty"),
+ ({"provider": "launchd", "id": "launchd:already"}, "without the"),
+ ({"provider": "launchd", "id": "arch:portal"}, "not a valid"),
+ ({"provider": "launchd"}, "non-empty"),
+ ("launchd:x", "must be an object"),
+ ):
+ with pytest.raises(ValueError, match=reason):
+ store.normalize_runtime_binding(bad)
+
+
+def test_manifest_carries_binding_and_annotation_names_the_runtime(home, tmp_path):
+ _write_manifest(tmp_path, "demo", runtime={"provider": "launchd", "id": "demo"})
+ manifest = store.load_manifest("demo")
+ assert manifest["runtime"] == {"provider": "launchd", "id": "demo", "graph_id": "launchd:demo"}
+ assert store.status_for(manifest)["runtime"] == "launchd:demo"
+ assert store.status_for(manifest)["ref"] == "arch:demo", "the RPC reference stays the manifest id"
+ store.manifests_dir().joinpath("broken.json").write_text(json.dumps({
+ "name": "B", "description": "d", "root": str(tmp_path / "demo"), "runtime": {"provider": "k8s", "id": "x"},
+ }), encoding="utf-8")
+ assert [m["id"] for m in store.list_manifests()] == ["demo"], "a malformed binding skips the manifest with a warning"
+
+
+# ── Composition ──────────────────────────────────────────────────────────────
+
+
+def test_standalone_manifest_keeps_its_own_node(home, tmp_path):
+ _write_manifest(tmp_path, "portal")
+ definitions = collect_architecture_definitions()
+ assert [d["graph_id"] for d in definitions] == ["arch:portal"] and definitions[0]["runtime"] is None
+ services = service_graph.attach_architecture([_runtime("launchd:other")], definitions)
+ assert [s["id"] for s in services] == ["launchd:other", "arch:portal"]
+ assert "architecture" not in services[0]
+ assert services[1]["architecture"]["ref"] == "arch:portal"
+ assert collect_architecture_services()[0]["id"] == "arch:portal", "the standalone collector is unchanged"
+
+
+@pytest.mark.parametrize("provider, runtime_id, graph_id", [
+ ("launchd", "demo", "launchd:demo"),
+ ("docker", "0123456789abcdef", "docker:0123456789ab"),
+ ("nomad", "demo-job", "nomad:demo-job"),
+ ("process", "proc_0123456789ab", "proc_0123456789ab"),
+])
+def test_bound_manifest_annotates_the_runtime_node_and_adds_none(home, tmp_path, provider, runtime_id, graph_id):
+ root = _write_manifest(tmp_path, "demo", runtime={"provider": provider, "id": runtime_id})
+ runtime = _runtime(graph_id, source_files=["/opt/demo/serve.py", str(root / "scripts/build.py")])
+ services = service_graph.attach_architecture([runtime], collect_architecture_definitions())
+ assert [s["id"] for s in services] == [graph_id], "one node per logical service"
+ merged = services[0]
+ # Runtime stays authoritative for what it owns.
+ assert merged["health"]["status"] == "healthy"
+ assert merged["description"] == "Runs the demo."
+ assert merged["label"] == "Demo runtime"
+ assert merged["inputs"] == runtime["inputs"] and merged["outputs"] == runtime["outputs"]
+ assert merged["side_effects"] == runtime["side_effects"]
+ # The manifest contributes the annotation and its code; the union is sorted and deduplicated.
+ assert merged["architecture"]["ref"] == "arch:demo" and merged["architecture"]["runtime"] == graph_id
+ assert merged["source_files"] == sorted({"/opt/demo/serve.py", str(root / "architecture/model/model.json"), str(root / "scripts/build.py")})
+ assert runtime["source_files"] == ["/opt/demo/serve.py", str(root / "scripts/build.py")], "the provider's declaration is not mutated"
+ assert collect_architecture_services() == [], "a bound definition is not a service of its own"
+
+
+def test_bound_manifest_on_the_graph(home, tmp_path):
+ root = _write_manifest(tmp_path, "demo", runtime={"provider": "launchd", "id": "demo"})
+ runtime = _runtime("launchd:demo")
+ services = service_graph.attach_architecture([runtime], collect_architecture_definitions())
+ graph = build_cron_graph(jobs=[], services=services)
+ ids = [n["id"] for n in graph["nodes"] if n["kind"] == "service"]
+ assert ids == ["launchd:demo"] and "arch:demo" not in {n["id"] for n in graph["nodes"]}
+ node = next(n for n in graph["nodes"] if n["id"] == "launchd:demo")
+ assert node["health"]["status"] == "healthy"
+ assert node["architecture"]["ref"] == "arch:demo"
+ by_rel = {f.get("rel"): f for f in node["source_files"]}
+ assert by_rel["scripts/build.py"]["root"] == "arch-demo" and by_rel["scripts/build.py"]["exists"] is True
+ assert any(f["path"] == "/opt/demo/serve.py" and f["exists"] is False for f in node["source_files"])
+ # Topology comes from the runtime declaration alone: the manifest's own outputs are not drawn.
+ edges = {(e["source"], e["target"], e["type"]) for e in graph["edges"] if "launchd:demo" in (e["source"], e["target"])}
+ assert ("launchd:demo", "https:127.0.0.1:9000", "writes") in edges
+ assert not any("7000" in t for _, t, _ in edges), "the manifest's https:127.0.0.1:7000 output is not on the graph"
+ assert files_browse.file_roots()["arch-demo"] == root.resolve(), "the model root is browsable regardless of binding"
+ # The annotation stays outside the commitment digest.
+ bare = build_cron_graph(jobs=[], services=[_runtime("launchd:demo")])
+ assert configuration_digest(graph) == configuration_digest(bare)
+
+
+def test_missing_runtime_target_hides_the_definition_without_fabricating_a_node(home, tmp_path, caplog):
+ _write_manifest(tmp_path, "demo", runtime={"provider": "launchd", "id": "gone"})
+ with caplog.at_level(logging.WARNING, logger="tools.service_graph"):
+ services = service_graph.attach_architecture([_runtime("launchd:other")], collect_architecture_definitions())
+ assert [s["id"] for s in services] == ["launchd:other"]
+ assert "binds runtime service launchd:gone" in caplog.text
+ # Same outcome through the composed collector with providers that report nothing.
+ assert service_graph.collect_runtime_services(collectors={"launchd": lambda: []}) == []
+ # The model itself stays reachable over the RPC by its manifest id.
+ manifest = store.load_manifest("arch:demo")
+ assert store.describe(manifest, git_runner=lambda _r: "r1")["service"]["runtime"]["graph_id"] == "launchd:gone"
+
+
+def test_two_manifests_binding_one_runtime_are_both_rejected(home, tmp_path, caplog):
+ _write_manifest(tmp_path, "alpha", runtime={"provider": "launchd", "id": "demo"})
+ _write_manifest(tmp_path, "beta", runtime={"provider": "launchd", "id": "demo"})
+ with caplog.at_level(logging.WARNING, logger="tools.service_graph"):
+ services = service_graph.attach_architecture([_runtime("launchd:demo")], collect_architecture_definitions())
+ assert [s["id"] for s in services] == ["launchd:demo"]
+ assert "architecture" not in services[0], "no last-writer-wins"
+ assert "2 manifests bind runtime service launchd:demo (alpha, beta)" in caplog.text
+
+
+def test_source_file_union_is_deterministic():
+ merged = service_graph._merged_source_files(["/b/two.py", "/a/one.py", "/a/./one.py", " "], ["/a/one.py", "/c/three.py"])
+ assert merged == ["/a/one.py", "/b/two.py", "/c/three.py"]
+
+
+def test_collect_runtime_services_is_ordered_and_fail_open(caplog):
+ def boom():
+ raise RuntimeError("docker down")
+
+ collectors = {
+ "nomad": lambda: [{"id": "nomad:z"}],
+ "docker": boom,
+ "launchd": lambda: [{"id": "launchd:a"}],
+ }
+ with caplog.at_level(logging.ERROR, logger="tools.service_graph"):
+ services = service_graph.collect_runtime_services(collectors=collectors)
+ assert [s["id"] for s in services] == ["launchd:a", "nomad:z"], "provider order, not completion order"
+ assert "service overlay unavailable: docker" in caplog.text
+
+
+def test_collect_graph_services_composes_end_to_end(home, tmp_path, monkeypatch):
+ root = _write_manifest(tmp_path, "demo", runtime={"provider": "launchd", "id": "demo"})
+ _write_manifest(tmp_path, "portal")
+ monkeypatch.setattr(service_graph, "_runtime_collectors", lambda: {"launchd": lambda: [_runtime("launchd:demo")]})
+ services = service_graph.collect_graph_services()
+ assert [s["id"] for s in services] == ["launchd:demo", "arch:portal"]
+ assert services[0]["architecture"]["ref"] == "arch:demo"
+ assert str(root / "scripts/build.py") in services[0]["source_files"]
+
+
+def test_rpc_identity_stays_the_manifest_id_for_bound_models(home, tmp_path):
+ import tui_gateway.methods_architecture as ma
+
+ _write_manifest(tmp_path, "demo", runtime={"provider": "launchd", "id": "demo"})
+ pending = dict(ma._registry._pending)
+ for fn in pending.values():
+ fn.__globals__["_ok"] = lambda rid, result: {"result": result}
+ fn.__globals__["_err"] = lambda rid, code, msg: {"error": {"code": code, "message": msg}}
+ fn.__globals__["_broadcast_global_event"] = lambda event, payload=None: None
+ fn.__globals__.setdefault("logger", logging.getLogger("t"))
+ listed = pending["architecture.list"](1, {})["result"]["services"]
+ assert listed[0]["id"] == "arch:demo" and listed[0]["runtime"]["graph_id"] == "launchd:demo"
+ described = pending["architecture.describe"](2, {"service": "arch:demo"})["result"]
+ assert described["service"]["id"] == "arch:demo" and described["service"]["runtime"]["graph_id"] == "launchd:demo"
+ assert pending["architecture.history"](3, {"service": "demo"})["result"]["latest"] == described["revision"]
+ assert pending["architecture.describe"](4, {"service": "launchd:demo"})["error"]["code"] == 4030, "the graph id is not the RPC id"
+
+
+@pytest.fixture(autouse=True)
+def _fresh_runtime_cache():
+ service_graph.reset_runtime_cache()
+ yield
+ service_graph.reset_runtime_cache()
+
+
+def _counting_collectors(calls):
+ def launchd():
+ calls.append(1)
+ return [_runtime("launchd:demo")]
+ return lambda: {"launchd": launchd}
+
+
+def test_collect_graph_services_reuses_runtime_probes_within_ttl(home, monkeypatch):
+ calls = []
+ monkeypatch.setattr(service_graph, "_runtime_collectors", _counting_collectors(calls))
+ monkeypatch.setenv("HERMES_SERVICE_GRAPH_TTL", "10")
+ now = [1000.0]
+ monkeypatch.setattr(service_graph.time, "monotonic", lambda: now[0])
+
+ first = service_graph.collect_graph_services()
+ second = service_graph.collect_graph_services()
+ assert len(calls) == 1, "second call inside the TTL must not re-run the probes"
+ assert first == second and first is not second
+ first[0]["health"] = "mutated-by-caller"
+ assert service_graph.collect_graph_services()[0].get("health") != "mutated-by-caller", "cache hands out copies"
+
+ now[0] += 10.5
+ service_graph.collect_graph_services()
+ assert len(calls) == 2, "probes run again once the TTL has elapsed"
+
+
+def test_collect_graph_services_ttl_zero_disables_cache(home, monkeypatch):
+ calls = []
+ monkeypatch.setattr(service_graph, "_runtime_collectors", _counting_collectors(calls))
+ monkeypatch.setenv("HERMES_SERVICE_GRAPH_TTL", "0")
+ service_graph.collect_graph_services()
+ service_graph.collect_graph_services()
+ assert len(calls) == 2
+
+ monkeypatch.setenv("HERMES_SERVICE_GRAPH_TTL", "garbage")
+ assert service_graph.runtime_cache_ttl() == 0.0
+ monkeypatch.delenv("HERMES_SERVICE_GRAPH_TTL")
+ assert service_graph.runtime_cache_ttl() == 10.0
diff --git hermes-agent/tests/cron/test_architecture_services.py harness/tests/cron/test_architecture_services.py
new file mode 100644
index 0000000000000000000000000000000000000000..f9349207e95d620a9430b2933546b0046941837d
--- /dev/null
+++ harness/tests/cron/test_architecture_services.py
@@ -0,0 +1,86 @@
+"""Manifest-declared services join the dataflow graph with their code and model."""
+import json
+
+import pytest
+
+from cron.jobs import build_cron_graph
+from tools.architecture_services import collect_architecture_services
+from tests.gateway.architecture_fixtures import log_sink, minimal_document
+from tui_gateway import architecture_store as store
+from tui_gateway import files_browse
+
+
+@pytest.fixture
+def home(tmp_path, monkeypatch):
+ root = tmp_path / ".hermes"
+ monkeypatch.setenv("HERMES_HOME", str(root))
+ return root
+
+
+def _write_service(tmp_path, **extra):
+ root = tmp_path / "svc"
+ (root / "architecture" / "model").mkdir(parents=True)
+ (root / "scripts").mkdir()
+ (root / "scripts" / "build.py").write_text("print('hi')\n", encoding="utf-8")
+ (root / "architecture" / "model" / "model.json").write_text(json.dumps(minimal_document()), encoding="utf-8")
+ manifest = {
+ "name": "Demo", "description": "A **demo** service.", "root": str(root), "logs": [log_sink(root)],
+ "source_files": ["scripts/build.py", "scripts/missing.py"],
+ "inputs": ["file:~/.hermes/config.yaml"], "outputs": ["https:127.0.0.1:9000"], "side_effects": ["notify:ops"],
+ }
+ manifest.update(extra)
+ store.manifests_dir().mkdir(parents=True, exist_ok=True)
+ (store.manifests_dir() / "demo.json").write_text(json.dumps(manifest), encoding="utf-8")
+ return root
+
+
+def test_collector_declares_the_service_with_absolute_source_files(home, tmp_path):
+ root = _write_service(tmp_path)
+ (service,) = collect_architecture_services()
+ assert service["id"] == "arch:demo" and service["label"] == "Demo"
+ assert service["description"] == "A **demo** service."
+ assert service["inputs"] == ["file:~/.hermes/config.yaml"] and service["outputs"] == ["https:127.0.0.1:9000"]
+ assert service["side_effects"] == ["notify:ops"]
+ assert service["source_files"] == sorted({
+ str(root / "architecture/model/model.json"), str(root / "scripts/build.py"), str(root / "scripts/missing.py"),
+ })
+ assert service["architecture"]["ref"] == "arch:demo" and service["architecture"]["source"] == "local"
+
+
+def test_github_service_has_no_local_files(home, tmp_path):
+ store.manifests_dir().mkdir(parents=True, exist_ok=True)
+ (store.manifests_dir() / "remote.json").write_text(json.dumps({
+ "name": "Remote", "description": "Lives on GitHub.", "repository": "o/r", "ref": "main",
+ }), encoding="utf-8")
+ (service,) = collect_architecture_services()
+ assert service["source_files"] == [] and service["architecture"]["source"] == "github"
+ assert service["architecture"]["revision"] == "main"
+
+
+def test_collector_skips_a_manifest_the_graph_rejects(home, tmp_path):
+ _write_service(tmp_path, outputs=["cron-output:reserved"])
+ assert collect_architecture_services() == []
+
+
+def test_service_node_carries_files_and_architecture_and_its_root_is_browsable(home, tmp_path):
+ root = _write_service(tmp_path)
+ roots = files_browse.file_roots()
+ assert roots["arch-demo"] == root.resolve(), "the checkout is a read-only browse root"
+ graph = build_cron_graph(jobs=[], services=collect_architecture_services())
+ node = next(n for n in graph["nodes"] if n["id"] == "arch:demo")
+ assert node["kind"] == "service" and node["architecture"]["ref"] == "arch:demo"
+ by_rel = {f["rel"]: f for f in node["source_files"]}
+ assert by_rel["scripts/build.py"]["root"] == "arch-demo" and by_rel["scripts/build.py"]["exists"] is True
+ assert by_rel["scripts/missing.py"]["exists"] is False, "a declared file that does not exist yet is listed, not dropped"
+ assert by_rel["architecture/model/model.json"]["role"] == "declared"
+ listing = files_browse.list_tree("arch-demo", "scripts")
+ assert [e["path"] for e in listing["entries"]] == ["scripts/build.py"]
+ assert files_browse.read_file("arch-demo", "scripts/build.py")["content"] == "print('hi')\n"
+
+
+def test_missing_root_directory_is_not_advertised(home, tmp_path):
+ store.manifests_dir().mkdir(parents=True, exist_ok=True)
+ (store.manifests_dir() / "gone.json").write_text(json.dumps({
+ "name": "Gone", "description": "Root was deleted.", "root": str(tmp_path / "nowhere"),
+ }), encoding="utf-8")
+ assert "arch-gone" not in files_browse.file_roots()
diff --git hermes-agent/tests/gateway/architecture_fixtures.py harness/tests/gateway/architecture_fixtures.py
new file mode 100644
index 0000000000000000000000000000000000000000..f35509b910da2131cd2e587dfb5f96f352d860e2
--- /dev/null
+++ harness/tests/gateway/architecture_fixtures.py
@@ -0,0 +1,124 @@
+"""The smallest architecture document that conforms to hermes.architecture v1.
+
+Shared by every architecture test: the store validates each model it reads
+against the contract, so a fixture that is "just JSON with a schema_version"
+no longer gets through. ``minimal_document(**overrides)`` returns a fresh,
+conforming document (two components, two constructions with provenance, one
+mechanical pass, one flow, one holding and one violated invariant, one local
+gate feeding the merge, one store, two externals); pass top-level keys to
+override sections, or mutate the result.
+"""
+from __future__ import annotations
+
+import copy
+import json
+from pathlib import Path
+from typing import Any, Dict, List, Optional
+
+DIGEST = "0" * 64
+
+
+def _component(component_id: str, label: str) -> Dict[str, Any]:
+ return {
+ "id": component_id, "label": label, "description": f"The {label} component.", "layer": "core",
+ "files": [f"src/{component_id}.py"], "declarations": [label], "file_count": 1, "line_count": 10, "declaration_count": 1,
+ }
+
+
+_MINIMAL: Dict[str, Any] = {
+ "schema_version": "1.0.0",
+ "title": "Demo",
+ "description": "A demo architecture model.",
+ "repository": None,
+ "source_tree_sha256": DIGEST,
+ "components": [_component("a", "Alpha"), _component("b", "Beta")],
+ "interplay": {
+ "nodes": [
+ {"id": "n1", "kind": "store", "label": "Alpha", "component": "a", "path": "src/a.py", "line": 1, "history_key": "store:a:Alpha"},
+ {"id": "n2", "kind": "endpoint", "label": "Beta", "component": "b", "path": "src/b.py", "line": 1, "history_key": "endpoint:b:Beta"},
+ ],
+ "edges": [{"source": "n1", "target": "n2", "relation": "calls", "class": "interplay"}],
+ "flows": [{"id": "f1", "title": "Alpha calls Beta", "steps": [{"from": "store:a:Alpha", "to": "n2", "relation": "calls"}]}],
+ "invariants": [
+ {"id": "one", "kind": "single_transport", "status": "holds", "why": "One transport.", "checked": 1},
+ {"id": "two", "kind": "stores_mapped", "status": "violated", "why": "Every store is on the map.", "checked": 1},
+ ],
+ "pages": [{"id": "home", "label": "Home"}],
+ },
+ "extraction": {
+ "authority": "observed",
+ "derivation": "Every (pass, file, line) the model cites, joined to declarations by line range.",
+ "files": [
+ {"path": "src/a.py", "component": "a", "line_count": 10, "citations": 1, "semantic_citations": 0, "touched": True,
+ "declaration_count": 1, "mapped_declarations": 1, "passes": ["py.class"],
+ "declarations": [{"kind": "class", "name": "Alpha", "line": 1, "passes": ["py.class"]}]},
+ {"path": "src/b.py", "component": "b", "line_count": 10, "citations": 1, "semantic_citations": 0, "touched": True,
+ "declaration_count": 1, "mapped_declarations": 1, "passes": ["py.class"],
+ "declarations": [{"kind": "class", "name": "Beta", "line": 1, "passes": ["py.class"]}]},
+ {"path": "src/untouched.py", "component": "b", "line_count": 4, "citations": 0, "semantic_citations": 1, "touched": False,
+ "declaration_count": 1, "mapped_declarations": 0, "passes": [],
+ "declarations": [{"kind": "func", "name": "helper", "line": 1, "passes": []}]},
+ ],
+ "passes": [
+ {"id": "py.class", "class": "mechanical", "description": "A class declaration.", "files": 2, "citations": 2},
+ {"id": "semantic.construct", "class": "semantic", "description": "A construct record written by a person.", "files": 1, "citations": 1},
+ ],
+ "entities": [
+ {"id": "n1", "kind": "store", "label": "Alpha", "component": "a", "origins": [{"path": "src/a.py", "line": 1, "rule": "py.class", "family": "store"}]},
+ {"id": "n2", "kind": "endpoint", "label": "Beta", "component": "b", "origins": [{"path": "src/b.py", "line": 1, "rule": "py.class", "family": "wiring"}]},
+ ],
+ "summary": {
+ "files": 3, "touched_files": 2, "untouched_files": 1, "declarations": 3, "mapped_declarations": 2,
+ "entities": 2, "entities_with_origin": 2, "passes": 1, "citations": 2, "semantic_citations": 1,
+ },
+ },
+ "ci": {
+ "workflows": [{"id": "local", "label": "Local checks", "name": "Local checks", "family": "posture", "jobs": ["local/check"], "events": ["manual"]}],
+ "jobs": [{"id": "local/check", "key": "check", "name": "Compiler check", "workflow": "local", "family": "posture", "role": "local", "needs": [],
+ "steps": [{"command": "python3 build.py --check"}], "step_count": 1, "scripts": ["build.py"]}],
+ "edges": [{"source": "local/check", "target": "merge:accept", "kind": "gates"}],
+ "triggers": [],
+ "merge": {"id": "merge:accept", "label": "Accepted", "inputs": ["local/check"]},
+ "ratchets": [],
+ "static_checks": [{"name": "Compiler check", "command": "python3 build.py --check", "job": "local/check", "scripts": ["build.py"]}],
+ "limitations": [],
+ "summary": {"workflows": 7, "jobs": 1, "gates": 14, "ratchets": 7, "static_checks": 1},
+ },
+ "inventory": {"files": 3, "lines": 120, "declarations": 3},
+ "evidence_metadata": {"class": "static_source", "rules": {"py.class": "A class declaration."}, "limitations": []},
+ "stores": {"count": 1, "items": [{"id": "s", "label": "S", "kind": "class", "type_name": "S", "component": "a"}]},
+ "externals": {"systems": [{"id": "x", "label": "X", "category": "backend"}, {"id": "y", "label": "Y", "category": "backend"}]},
+}
+
+
+def minimal_document(**overrides: Any) -> Dict[str, Any]:
+ """A fresh conforming document; ``overrides`` replace top-level keys."""
+ document = copy.deepcopy(_MINIMAL)
+ document.update(overrides)
+ return document
+
+
+def log_sink(root: Path, sink_id: str = "app", text: str = "started\n") -> Dict[str, Any]:
+ """A ``file`` log sink under ``root/logs`` with ``text`` already written —
+ log capture is enforced for local services, so every local test manifest
+ declares one."""
+ path = Path(root) / "logs" / f"{sink_id}.log"
+ path.parent.mkdir(parents=True, exist_ok=True)
+ path.write_text(text, encoding="utf-8")
+ return {"id": sink_id, "kind": "file", "path": str(path)}
+
+
+def local_manifest(root: Path, name: str = "Demo", description: str = "A demo service.",
+ logs: Optional[List[Dict[str, Any]]] = None, **extra: Any) -> Dict[str, Any]:
+ """A conforming local manifest dict: root, a declared log sink, plus ``extra``."""
+ manifest: Dict[str, Any] = {"name": name, "description": description, "root": str(root),
+ "logs": logs if logs is not None else [log_sink(Path(root))]}
+ manifest.update(extra)
+ return manifest
+
+
+def write_manifest(manifests_dir: Path, service_id: str, manifest: Dict[str, Any]) -> Path:
+ manifests_dir.mkdir(parents=True, exist_ok=True)
+ path = manifests_dir / f"{service_id}.json"
+ path.write_text(json.dumps(manifest), encoding="utf-8")
+ return path
diff --git hermes-agent/tests/gateway/test_architecture_contract.py harness/tests/gateway/test_architecture_contract.py
new file mode 100644
index 0000000000000000000000000000000000000000..3629250c458b8d7c3624e708e52d9c4ad4bcc33d
--- /dev/null
+++ harness/tests/gateway/test_architecture_contract.py
@@ -0,0 +1,200 @@
+"""The hermes.architecture v1 contract at the gateway: a document is validated on
+every read, refused (4033) and never snapshotted when it does not conform, and
+served with the contract named in the envelope, the node annotation and the
+capabilities (tui_gateway.architecture_contract, architecture_store, handlers)."""
+import copy
+import json
+import logging
+from pathlib import Path
+
+import pytest
+
+import tui_gateway.methods_architecture as ma
+import tui_gateway.methods_harness as mh
+from tests.gateway.architecture_fixtures import local_manifest, minimal_document
+from tui_gateway import architecture_contract as contract
+from tui_gateway import architecture_store as store
+
+ROOT = Path(__file__).resolve().parents[2]
+
+
+@pytest.fixture
+def home(tmp_path, monkeypatch):
+ root = tmp_path / ".hermes"
+ monkeypatch.setenv("HERMES_HOME", str(root))
+ return root
+
+
+def _write_service(tmp_path, document, service_id="demo"):
+ root = tmp_path / service_id
+ (root / "architecture" / "model").mkdir(parents=True)
+ (root / "architecture" / "model" / "model.json").write_text(json.dumps(document), encoding="utf-8")
+ store.manifests_dir().mkdir(parents=True, exist_ok=True)
+ (store.manifests_dir() / f"{service_id}.json").write_text(json.dumps(
+ local_manifest(root, name=service_id.title(), description="A demo.")
+ ), encoding="utf-8")
+ return root
+
+
+def _stub(module):
+ pending = dict(module._registry._pending)
+ for fn in pending.values():
+ fn.__globals__["_ok"] = lambda rid, result: {"rid": rid, "result": result}
+ fn.__globals__["_err"] = lambda rid, code, msg: {"rid": rid, "error": {"code": code, "message": msg}}
+ fn.__globals__["_broadcast_global_event"] = lambda event, payload=None: None
+ fn.__globals__.setdefault("logger", logging.getLogger("test"))
+ return pending
+
+
+# ── The contract module ──────────────────────────────────────────────────────
+
+
+def test_minimal_document_conforms_and_names_the_contract():
+ document = minimal_document()
+ assert contract.validate_document(document) == []
+ assert contract.conforms(document)
+ assert contract.parse_version(document) == (1, 0, 0)
+ described = contract.describe_contract()
+ assert described["name"] == "hermes.architecture" and described["version"] == "1.0"
+ assert described["major"] == 1 and described["minor"] == 0
+ assert described["required_sections"] == ["components", "interplay", "extraction", "ci", "inventory", "evidence_metadata"]
+ assert described["optional_sections"] == ["stores", "externals", "layers", "edges", "behavior"]
+ assert described["schema_digest"] == contract.schema_digest()
+
+
+def test_unsupported_major_is_one_message_and_nothing_else_is_reported():
+ problems = contract.validate_document(minimal_document(schema_version="2.0.0"))
+ assert problems == ["document.schema_version: major 2 is not supported (this consumer speaks hermes.architecture v1.x)"]
+ assert contract.validate_document({"title": "x"}) == [
+ "document.schema_version: missing or not semver (contract hermes.architecture v1.0)",
+ ]
+ assert contract.validate_document("not a dict")[0].startswith("document.schema_version")
+ # A 1.x minor with fields this consumer has never heard of is accepted.
+ assert contract.validate_document(minimal_document(schema_version="1.7.2", future_section={"anything": 1})) == []
+
+
+@pytest.mark.parametrize("mutate, needle", [
+ (lambda d: d.pop("extraction"), "document: missing required field 'extraction'"),
+ (lambda d: d.pop("ci"), "document: missing required field 'ci'"),
+ (lambda d: d["interplay"]["edges"].append({"source": "n1", "target": "ghost", "relation": "calls", "class": "interplay"}),
+ "interplay.edges[1]: target 'ghost' is not a node"),
+ (lambda d: d["extraction"]["entities"].pop(), "extraction.entities: construction 'n2' has no provenance"),
+ (lambda d: d["extraction"]["entities"].append({"id": "orphan", "kind": "store", "label": "O", "origins": [{"path": "src/a.py", "line": 1, "rule": "py.class", "family": "store"}]}),
+ "extraction.entities: 'orphan' is not a construction on the map"),
+ (lambda d: d["ci"]["merge"]["inputs"].append("ghost/job"), "ci.merge: input 'ghost/job' is not a job"),
+ (lambda d: d["ci"]["merge"].__setitem__("inputs", []), "document.ci.merge.inputs: needs at least 1 item(s), has 0"),
+ (lambda d: d["extraction"]["files"][2].__setitem__("touched", True), "extraction.files[src/untouched.py]: touched must equal citations > 0"),
+ (lambda d: d["extraction"]["passes"].pop(0), "extraction.passes: no mechanical pass"),
+ (lambda d: d["interplay"]["invariants"][0].__setitem__("status", "maybe"), "document.interplay.invariants[0].status: 'maybe' is not one of"),
+ (lambda d: d["interplay"]["flows"][0]["steps"][0].__setitem__("to", "nowhere"), "interplay.flows[f1].steps[0]: to 'nowhere' is not on the map"),
+ (lambda d: d["ci"]["jobs"][0].__setitem__("role", "cron"), "document.ci.jobs[0].role: 'cron' is not one of"),
+])
+def test_each_loosening_is_named(mutate, needle):
+ document = minimal_document()
+ mutate(document)
+ problems = contract.validate_document(document)
+ assert any(needle in problem for problem in problems), f"{needle!r} not in {problems}"
+
+
+def test_a_file_cited_only_by_people_is_untouched():
+ document = minimal_document()
+ record = document["extraction"]["files"][2]
+ assert record["semantic_citations"] == 1 and record["citations"] == 0 and record["touched"] is False
+ assert contract.validate_document(document) == []
+
+
+def test_schema_export_and_digest_do_not_drift():
+ exported = (ROOT / "docs/api/architecture-document-v1.schema.json").read_text(encoding="utf-8")
+ assert exported == contract.schema_json(), "regenerate with: python3 tui_gateway/architecture_contract.py --schema"
+ docs = (ROOT / "docs/api/architecture.md").read_text(encoding="utf-8")
+ assert contract.schema_digest() in docs, "docs/api/architecture.md must quote the current schema digest"
+ schema = json.loads(exported)
+ assert schema["required"] == ["schema_version", "title", "description", "source_tree_sha256", *contract.REQUIRED_SECTIONS]
+
+
+# ── The store ────────────────────────────────────────────────────────────────
+
+
+def test_describe_refuses_a_nonconforming_model_and_stores_no_snapshot(home, tmp_path):
+ document = minimal_document()
+ del document["extraction"]
+ document["interplay"]["edges"].append({"source": "n1", "target": "ghost", "relation": "calls", "class": "interplay"})
+ _write_service(tmp_path, document)
+ manifest = store.load_manifest("demo")
+ with pytest.raises(store.ArchitectureError) as err:
+ store.describe(manifest, git_runner=lambda _root: "rev1")
+ assert err.value.code == 4033
+ assert "does not conform to hermes.architecture v1.0" in err.value.message
+ assert "missing required field 'extraction'" in err.value.message
+ assert store.list_snapshots("demo")["revisions"] == [], "nothing non-conforming is ever stored"
+ status = store.status_for(manifest)
+ assert status["conforming"] is False and "does not conform" in status["problem"]
+ assert status["contract"] == {"name": "hermes.architecture", "version": "1.0"}
+
+
+def test_message_shows_five_problems_and_counts_the_rest():
+ message = store.nonconforming_message("m.json", [f"p{i}" for i in range(8)])
+ assert message.endswith("p0; p1; p2; p3; p4 (+3 more)")
+ assert store.nonconforming_message("m.json", ["only"]).endswith(": only")
+
+
+def test_conforming_model_is_snapshotted_with_the_contract_in_the_envelope(home, tmp_path):
+ _write_service(tmp_path, minimal_document())
+ manifest = store.load_manifest("demo")
+ document = store.describe(manifest, git_runner=lambda _root: "rev1")
+ assert document["contract"] == contract.describe_contract()
+ assert document["summary"]["files"] == 3 and document["summary"]["lines"] == 120
+ index = store.list_snapshots("demo")
+ assert index["latest"] == "rev1"
+ assert index["revisions"][0]["contract"] == {"name": "hermes.architecture", "version": "1.0"}
+ status = store.status_for(manifest)
+ assert status["conforming"] is True and "problem" not in status
+ # A stored revision is served with the envelope too.
+ assert store.describe(manifest, revision="rev1")["contract"]["major"] == 1
+
+
+def test_github_conformance_follows_snapshots(home):
+ manifest = store.normalize_manifest({"name": "R", "description": "d", "repository": "o/r", "ref": "main"}, "remote")
+ unread = store.status_for(manifest)
+ assert unread["conforming"] is False and "not read yet" in unread["problem"]
+ opener = lambda url, headers: json.dumps(minimal_document(source_revision="abc")).encode("utf-8")
+ store.describe(manifest, opener=opener)
+ assert store.status_for(manifest)["conforming"] is True
+
+ bad = lambda url, headers: json.dumps(minimal_document(schema_version="9.0.0")).encode("utf-8")
+ with pytest.raises(store.ArchitectureError) as err:
+ store.describe(manifest, opener=bad)
+ assert err.value.code == 4033 and "major 9" in err.value.message
+
+
+# ── The handlers and the capabilities ────────────────────────────────────────
+
+
+def test_handlers_carry_the_contract_and_surface_4033(home, tmp_path):
+ pending = _stub(ma)
+ _write_service(tmp_path, minimal_document())
+ listed = pending["architecture.list"](1, {})["result"]
+ assert listed["contract"] == {"name": "hermes.architecture", "version": "1.0"}
+ (service,) = listed["services"]
+ assert service["status"]["conforming"] is True and service["status"]["contract"]["version"] == "1.0"
+ described = pending["architecture.describe"](2, {"service": "arch:demo"})["result"]
+ assert described["contract"]["name"] == "hermes.architecture" and described["contract"]["schema_digest"] == contract.schema_digest()
+ assert described["model"]["extraction"]["summary"]["entities"] == 2
+
+ broken = copy.deepcopy(minimal_document())
+ broken["ci"]["merge"]["inputs"] = ["nobody"]
+ (tmp_path / "demo" / "architecture" / "model" / "model.json").write_text(json.dumps(broken), encoding="utf-8")
+ refused = pending["architecture.describe"](3, {"service": "arch:demo"})
+ assert refused["error"]["code"] == 4033
+ assert "ci.merge: input 'nobody' is not a job" in refused["error"]["message"]
+ relisted = pending["architecture.list"](4, {})["result"]["services"][0]["status"]
+ assert relisted["conforming"] is False and "nobody" in relisted["problem"]
+
+
+def test_capabilities_advertise_the_contract():
+ pending = _stub(mh)
+ result = pending["gateway.capabilities"](1, {})["result"]
+ assert result["architecture"]["methods"] == ["architecture.list", "architecture.describe", "architecture.check", "architecture.history", "architecture.diff"]
+ assert result["architecture"]["contract"] == contract.describe_contract()
+ for name in result["architecture"]["methods"]:
+ assert name in result["capability_names"], "the flat list old clients read is unchanged"
diff --git hermes-agent/tests/gateway/test_architecture_history.py harness/tests/gateway/test_architecture_history.py
new file mode 100644
index 0000000000000000000000000000000000000000..58d279f267610bdf87f761ebf1d35ea4d1b5c8e6
--- /dev/null
+++ harness/tests/gateway/test_architecture_history.py
@@ -0,0 +1,266 @@
+"""Revision history and structural diffs: architecture.history joins snapshots to
+git and marks the deployed revision; architecture.diff compares two snapshots by
+stable identity (tui_gateway/architecture_store.py, methods_architecture.py)."""
+import copy
+import json
+import logging
+
+import pytest
+
+from tests.gateway.architecture_fixtures import minimal_document
+from tui_gateway import architecture_store as store
+import tui_gateway.methods_architecture as ma
+
+
+@pytest.fixture
+def home(tmp_path, monkeypatch):
+ root = tmp_path / ".hermes"
+ monkeypatch.setenv("HERMES_HOME", str(root))
+ return root
+
+
+@pytest.fixture
+def handlers():
+ pending = dict(ma._registry._pending)
+ events = []
+ for fn in pending.values():
+ fn.__globals__["_ok"] = lambda rid, result: {"rid": rid, "result": result}
+ fn.__globals__["_err"] = lambda rid, code, msg: {"rid": rid, "error": {"code": code, "message": msg}}
+ fn.__globals__["_broadcast_global_event"] = lambda event, payload=None: events.append((event, payload))
+ fn.__globals__.setdefault("logger", logging.getLogger("test"))
+ return pending, events
+
+
+def _write_manifest(tmp_path, stem="demo", **extra):
+ root = tmp_path / stem
+ (root / "architecture" / "model").mkdir(parents=True, exist_ok=True)
+ (root / "architecture" / "model" / "model.json").write_text(json.dumps(minimal_document()), encoding="utf-8")
+ manifest = {"name": stem.title(), "description": f"The {stem} service.", "root": str(root)}
+ manifest.update(extra)
+ store.manifests_dir().mkdir(parents=True, exist_ok=True)
+ (store.manifests_dir() / f"{stem}.json").write_text(json.dumps(manifest), encoding="utf-8")
+ return root
+
+
+SHA_A = "a" * 40
+SHA_B = "b" * 40
+SHA_C = "c" * 40
+
+
+def _fake_git(head=SHA_B, log=None, numstat=""):
+ """A git runner: rev-parse → head; log -1 <rev> → one line; log range → the
+ configured lines; diff --numstat → the configured text. Records calls."""
+ calls = []
+
+ def run(root, *args):
+ calls.append(args)
+ if args[:2] == ("rev-parse", "HEAD"):
+ return head
+ if args[0] == "log" and args[1] == "-1":
+ rev = args[-1]
+ return f"{rev}\x1fAda\x1f2026-09-25T10:00:00+00:00\x1fsubject for {rev[:4]}\n"
+ if args[0] == "log":
+ return log or ""
+ if args[0] == "diff":
+ return numstat
+ return ""
+
+ run.calls = calls
+ return run
+
+
+# ── diff_models: pure, identity-aware ───────────────────────────────────────
+
+
+def test_diff_models_reports_changes_by_stable_identity():
+ before = minimal_document()
+ after = copy.deepcopy(before)
+ # Rename a node (new id, same history_key): not churn.
+ after["interplay"]["nodes"][0]["id"] = "n1-renamed"
+ after["interplay"]["edges"][0]["source"] = "n1-renamed"
+ after["interplay"]["flows"][0]["steps"][0]["from"] = "store:a:Alpha"
+ # Add a node and an edge to it; remove nothing yet.
+ after["interplay"]["nodes"].append({"id": "n3", "kind": "caller", "label": "Gamma", "component": "a", "path": "src/a.py", "line": 5, "history_key": "caller:a:Gamma"})
+ after["interplay"]["edges"].append({"source": "n3", "target": "n2", "relation": "invokes", "class": "interplay"})
+ # Flip an invariant, add one, drop none.
+ after["interplay"]["invariants"][1]["status"] = "holds"
+ after["interplay"]["invariants"].append({"id": "three", "kind": "x", "status": "holds", "why": "w", "checked": 1})
+ # A file grows, one appears, one disappears.
+ after["extraction"]["files"][0]["line_count"] = 42
+ after["extraction"]["files"].append({"path": "src/new.py", "component": "a", "line_count": 3, "citations": 0, "semantic_citations": 0, "touched": False,
+ "declaration_count": 0, "mapped_declarations": 0, "passes": [], "declarations": []})
+ after["extraction"]["files"] = [f for f in after["extraction"]["files"] if f["path"] != "src/untouched.py"]
+ # A gate job appears.
+ after["ci"]["jobs"].append({"id": "local/lint", "name": "Lint", "workflow": after["ci"]["workflows"][0]["id"], "family": "posture", "role": "local", "needs": []})
+
+ result = store.diff_models(before, after)
+ assert [n["history_key"] for n in result["nodes"]["added"]] == ["caller:a:Gamma"]
+ assert result["nodes"]["added"][0]["label"] == "Gamma" and result["nodes"]["added"][0]["kind"] == "caller"
+ assert result["nodes"]["removed"] == [], "a rename that keeps the history key is not churn"
+ assert result["edges"]["added"] == [{"source": "caller:a:Gamma", "target": "endpoint:b:Beta", "relation": "invokes", "class": "interplay"}]
+ assert result["edges"]["removed"] == [], "the renamed node's edge resolves to the same keys"
+ assert result["invariants"] == {"added": ["three"], "removed": [], "changed": [{"id": "two", "from": "violated", "to": "holds"}]}
+ assert result["files"] == {"added": ["src/new.py"], "removed": ["src/untouched.py"], "changed": [{"path": "src/a.py", "lines_from": 10, "lines_to": 42}]}
+ assert result["gates"]["jobs_added"] == ["local/lint"] and result["gates"]["jobs_removed"] == []
+ assert result["gates"]["ratchets_added"] == [] and result["gates"]["ratchets_removed"] == []
+ assert result["summary"]["from"]["nodes"] == 2 and result["summary"]["to"]["nodes"] == 3
+ # Symmetric: swapping the arguments swaps added and removed.
+ reverse = store.diff_models(after, before)
+ assert [n["history_key"] for n in reverse["nodes"]["removed"]] == ["caller:a:Gamma"]
+ assert reverse["invariants"]["changed"] == [{"id": "two", "from": "holds", "to": "violated"}]
+ assert reverse["files"]["removed"] == ["src/new.py"]
+
+
+def test_diff_models_of_identical_documents_is_empty():
+ document = minimal_document()
+ result = store.diff_models(document, copy.deepcopy(document))
+ assert result["nodes"] == {"added": [], "removed": []}
+ assert result["edges"] == {"added": [], "removed": []}
+ assert result["invariants"] == {"added": [], "removed": [], "changed": []}
+ assert result["files"] == {"added": [], "removed": [], "changed": []}
+ assert all(value == [] for value in result["gates"].values())
+
+
+# ── git helpers ──────────────────────────────────────────────────────────────
+
+
+def test_commit_helpers_are_fail_open_and_bounded():
+ assert store.commit_info(None, SHA_A) is None
+ assert store.commit_info("/r", "working-tree", _fake_git()) is None
+ assert store.commit_info("/r", "sha256:abcd", _fake_git()) is None
+ assert store.commit_info("/r", SHA_A, _fake_git()) == {"sha": SHA_A, "author": "Ada", "date": "2026-09-25T10:00:00+00:00", "subject": f"subject for {SHA_A[:4]}"}
+ assert store.commit_info("/r", SHA_A, lambda root, *a: "") is None, "git failure is not an error"
+ assert store.commits_between("/r", None, SHA_A, _fake_git()) is None
+ assert store.commits_between("/r", "working-tree", SHA_A, _fake_git()) is None
+ lines = "".join(f"{i:040x}\x1fAda\x1f2026-09-25T10:{i:02d}:00+00:00\x1fc{i}\n" for i in range(60))
+ since = store.commits_between("/r", SHA_A, SHA_B, _fake_git(log=lines))
+ assert len(since) == 60 and since[0]["subject"] == "c0" and since[-1]["subject"] == "c59", "the runner is asked for at most 50; ordering is git's (oldest first)"
+ git = _fake_git(log="")
+ store.commits_between("/r", SHA_A, SHA_B, git)
+ assert git.calls[-1] == ("log", "--reverse", f"--max-count={store.MAX_HISTORY_COMMITS}", f"--format={store._GIT_LOG_FORMAT}", f"{SHA_A}..{SHA_B}")
+ stat = store.git_numstat("/r", SHA_A, SHA_B, _fake_git(numstat="3\t1\tsrc/a.py\n-\t-\tlogo.png\nbad line\n"))
+ assert stat == {"stat": [{"path": "src/a.py", "additions": 3, "deletions": 1}, {"path": "logo.png", "additions": None, "deletions": None}], "truncated": False}
+ big = "\n".join(f"1\t1\tf{i}.py" for i in range(store.MAX_DIFF_STAT + 5))
+ stat = store.git_numstat("/r", SHA_A, SHA_B, _fake_git(numstat=big))
+ assert len(stat["stat"]) == store.MAX_DIFF_STAT and stat["truncated"] is True
+
+
+def test_runtime_info_reports_launchd_pid_fail_open():
+ assert store.runtime_info({"name": "x"}) is None
+ manifest = {"runtime": {"provider": "launchd", "id": "ai.demo", "graph_id": "launchd:ai.demo"}}
+ info = store.runtime_info(manifest, runner=lambda args: "{\n\tstate = running\n\tpid = 4242\n}\n")
+ assert info == {"provider": "launchd", "graph_id": "launchd:ai.demo", "pid": 4242}
+
+ def boom(args):
+ raise RuntimeError("launchctl unavailable")
+
+ assert store.runtime_info(manifest, runner=boom) == {"provider": "launchd", "graph_id": "launchd:ai.demo"}
+ docker = {"runtime": {"provider": "docker", "id": "0123456789ab", "graph_id": "docker:0123456789ab"}}
+ assert store.runtime_info(docker, runner=boom) == {"provider": "docker", "graph_id": "docker:0123456789ab"}
+
+
+# ── history() ────────────────────────────────────────────────────────────────
+
+
+def _store_three(tmp_path):
+ root = _write_manifest(tmp_path)
+ manifest = store.load_manifest("demo")
+ for revision in (SHA_A, SHA_B, SHA_C):
+ model = minimal_document()
+ model["title"] = f"Demo@{revision[:4]}"
+ store.store_snapshot("demo", revision, model, "local")
+ return root, manifest
+
+
+def test_history_joins_snapshots_to_git_and_marks_the_deployed_revision(home, tmp_path):
+ _root, manifest = _store_three(tmp_path)
+ git = _fake_git(head=SHA_B, log=f"{'d' * 40}\x1fBob\x1f2026-09-25T11:00:00+00:00\x1fbetween\n")
+ result = store.history(manifest, git=git)
+ assert result["service"] == "arch:demo" and result["latest"] == SHA_C and result["head"] == SHA_B
+ revisions = result["revisions"]
+ assert [r["revision"] for r in revisions] == [SHA_A, SHA_B, SHA_C], "genesis first, newest last"
+ assert [r["deployed"] for r in revisions] == [False, True, False], "deployed = the snapshot at the checkout's HEAD"
+ assert revisions[1]["deployed_at"] == revisions[1]["stored_at"] and "deployed_at" not in revisions[0]
+ assert revisions[0]["commit"]["sha"] == SHA_A and revisions[2]["commit"]["subject"] == f"subject for {SHA_C[:4]}"
+ assert "commits_since_previous" not in revisions[0], "genesis has no previous snapshot"
+ assert revisions[1]["commits_since_previous"] == [{"sha": "d" * 40, "author": "Bob", "date": "2026-09-25T11:00:00+00:00", "subject": "between"}]
+ assert "runtime" not in result and result["checks"] == []
+ # Existing fields survive.
+ assert set(revisions[0]) >= {"revision", "source", "stored_at", "summary", "contract"}
+
+
+def test_history_without_git_and_for_github_services(home, tmp_path):
+ _root, manifest = _store_three(tmp_path)
+ store.store_snapshot("demo", "working-tree", minimal_document(), "local")
+ result = store.history(manifest, git=lambda root, *a: "")
+ # No git: the checkout's revision is the model's content digest, which no
+ # stored git revision equals, so nothing is marked deployed.
+ assert str(result["head"]).startswith("sha256:")
+ assert all(r["deployed"] is False for r in result["revisions"])
+ assert all("commit" not in r for r in result["revisions"])
+ assert "commits_since_previous" not in result["revisions"][-1], "a working-tree revision is not a commit range end"
+ store.manifests_dir().joinpath("remote.json").write_text(json.dumps({
+ "name": "Remote", "description": "d", "repository": "o/r", "ref": "main", "model": "architecture/model/model.json",
+ }), encoding="utf-8")
+ remote = store.load_manifest("remote")
+ store.store_snapshot("remote", "v1", minimal_document(), "github")
+ result = store.history(remote, git=_fake_git())
+ assert result["source"] == "github" and result["head"] is None
+ assert result["revisions"][0]["deployed"] is False and "commit" not in result["revisions"][0]
+
+
+def test_history_carries_runtime_when_bound(home, tmp_path):
+ _write_manifest(tmp_path, runtime={"provider": "launchd", "id": "ai.demo"})
+ manifest = store.load_manifest("demo")
+ result = store.history(manifest, git=_fake_git(), runtime_runner=lambda args: "pid = 7\n")
+ assert result["runtime"] == {"provider": "launchd", "graph_id": "launchd:ai.demo", "pid": 7}
+
+
+# ── diff() and the handlers ──────────────────────────────────────────────────
+
+
+def test_diff_defaults_and_git_block(home, tmp_path):
+ _root, manifest = _store_three(tmp_path)
+ git = _fake_git(log=f"{'e' * 40}\x1fEve\x1f2026-09-25T12:00:00+00:00\x1fchange\n", numstat="5\t2\tsrc/b.py\n")
+ result = store.diff(manifest, git=git)
+ assert (result["from"], result["to"]) == (SHA_B, SHA_C), "to defaults to latest, from to the one before"
+ assert result["summary"]["to"]["title"] == f"Demo@{SHA_C[:4]}" and result["summary"]["from"]["title"] == f"Demo@{SHA_B[:4]}"
+ assert result["git"] == {"commits": [{"sha": "e" * 40, "author": "Eve", "date": "2026-09-25T12:00:00+00:00", "subject": "change"}],
+ "stat": [{"path": "src/b.py", "additions": 5, "deletions": 2}], "truncated": False}
+ explicit = store.diff(manifest, SHA_A, SHA_C, git=git)
+ assert (explicit["from"], explicit["to"]) == (SHA_A, SHA_C)
+ with pytest.raises(store.ArchitectureError) as missing:
+ store.diff(manifest, "nope", SHA_C, git=git)
+ assert missing.value.code == 4404
+ with pytest.raises(store.ArchitectureError) as genesis:
+ store.diff(manifest, None, SHA_A, git=git)
+ assert genesis.value.code == 4404 and "before" in genesis.value.message
+ store.store_snapshot("demo", "working-tree", minimal_document(), "local")
+ assert "git" not in store.diff(manifest, git=git), "no git block when an end is not a commit"
+
+
+def test_handlers_history_diff_and_is_latest(home, tmp_path, handlers):
+ pending, _events = handlers
+ _store_three(tmp_path)
+ history = pending["architecture.history"](1, {"service": "arch:demo"})["result"]
+ assert history["latest"] == SHA_C and [r["revision"] for r in history["revisions"]] == [SHA_A, SHA_B, SHA_C]
+ assert all("deployed" in r for r in history["revisions"]) and "checks" in history
+ diff = pending["architecture.diff"](2, {"service": "demo"})["result"]
+ assert (diff["from"], diff["to"]) == (SHA_B, SHA_C) and diff["nodes"] == {"added": [], "removed": []}
+ assert pending["architecture.diff"](3, {"service": "demo", "from": SHA_A, "to": SHA_B})["result"]["from"] == SHA_A
+ assert pending["architecture.diff"](4, {"service": "demo", "to": "nope"})["error"]["code"] == 4404
+ assert pending["architecture.diff"](5, {"service": "demo", "from": " "})["error"]["code"] == 4001
+ assert pending["architecture.diff"](6, {"service": "demo", "from": 7})["error"]["code"] == 4001
+ older = pending["architecture.describe"](7, {"service": "demo", "revision": SHA_A})["result"]
+ assert older["is_latest"] is False and older["revision"] == SHA_A
+ latest = pending["architecture.describe"](8, {"service": "demo", "revision": SHA_C})["result"]
+ assert latest["is_latest"] is True
+
+
+def test_capabilities_and_pool_advertise_diff():
+ capabilities = open("tui_gateway/methods_harness.py", encoding="utf-8").read()
+ assert capabilities.count('"architecture.diff"') == 2, "the methods list and capability_names"
+ server = open("tui_gateway/server.py", encoding="utf-8").read()
+ assert '"architecture.diff",' in server
+ docs = open("docs/api/architecture.md", encoding="utf-8").read()
+ assert "`architecture.diff`" in docs and "## Revision history" in docs
diff --git hermes-agent/tests/gateway/test_architecture_store.py harness/tests/gateway/test_architecture_store.py
new file mode 100644
index 0000000000000000000000000000000000000000..0479723b2b2284b4010e0f19f3b8a02cd000436c
--- /dev/null
+++ harness/tests/gateway/test_architecture_store.py
@@ -0,0 +1,233 @@
+"""Architecture manifests, model reads, snapshots and checks (tui_gateway.architecture_store)."""
+import json
+import subprocess
+from pathlib import Path
+
+import pytest
+
+from tests.gateway.architecture_fixtures import DIGEST, local_manifest, minimal_document
+from tui_gateway import architecture_store as store
+
+
+@pytest.fixture
+def home(tmp_path, monkeypatch):
+ # get_hermes_home() reads HERMES_HOME live — no cache to reset.
+ root = tmp_path / ".hermes"
+ monkeypatch.setenv("HERMES_HOME", str(root))
+ return root
+
+
+def _model(**extra):
+ return minimal_document(**extra)
+
+
+def _write_service(home: Path, tmp_path: Path, service_id="demo", **manifest_extra):
+ root = tmp_path / "svc"
+ (root / "architecture" / "model").mkdir(parents=True)
+ (root / "architecture" / "model" / "model.json").write_text(json.dumps(_model()), encoding="utf-8")
+ manifest = local_manifest(root)
+ manifest.update(manifest_extra)
+ store.manifests_dir().mkdir(parents=True, exist_ok=True)
+ (store.manifests_dir() / f"{service_id}.json").write_text(json.dumps(manifest), encoding="utf-8")
+ return root
+
+
+# ── Manifests ────────────────────────────────────────────────────────────────
+
+
+def test_normalize_manifest_defaults_and_rejections(tmp_path):
+ good = store.normalize_manifest({"name": "P", "description": "d", "root": str(tmp_path)}, "p")
+ assert good["id"] == "p" and good["model"] == store.DEFAULT_MODEL_PATH and good["ref"] == "main"
+ assert good["check"] is None and good["source_files"] == [] and good["repository"] is None
+ gh = store.normalize_manifest({"name": "P", "description": "d", "repository": "o/r", "ref": "v1.2"}, "p")
+ assert gh["root"] is None and store.source_of(gh) == "github" and store.source_of(good) == "local"
+ for bad, reason in (
+ ({"name": "P", "description": "d"}, "root or a GitHub"),
+ ({"name": "", "description": "d", "root": str(tmp_path)}, "name is required"),
+ ({"name": "P", "description": " ", "root": str(tmp_path)}, "description is required"),
+ ({"name": "P", "description": "d", "root": "relative/path"}, "absolute"),
+ ({"name": "P", "description": "d", "repository": "not-a-repo"}, "owner/name"),
+ ({"name": "P", "description": "d", "root": str(tmp_path), "model": "../x.json"}, "inside the service"),
+ ({"name": "P", "description": "d", "root": str(tmp_path), "check": "make check"}, "argv list"),
+ ({"id": "Other", "name": "P", "description": "d", "root": str(tmp_path)}, "must match"),
+ ({"id": "other", "name": "P", "description": "d", "root": str(tmp_path)}, "file name"),
+ ):
+ with pytest.raises(ValueError, match=reason):
+ store.normalize_manifest(bad, "p")
+ with pytest.raises(ValueError, match="JSON object"):
+ store.normalize_manifest([], "p")
+
+
+def test_list_and_load_manifests_skip_malformed(home, tmp_path):
+ _write_service(home, tmp_path)
+ store.manifests_dir().joinpath("broken.json").write_text("{not json", encoding="utf-8")
+ store.manifests_dir().joinpath("nameless.json").write_text(json.dumps({"root": str(tmp_path)}), encoding="utf-8")
+ manifests = store.list_manifests()
+ assert [m["id"] for m in manifests] == ["demo"]
+ assert store.load_manifest("demo")["name"] == "Demo"
+ assert store.load_manifest("arch:demo")["id"] == "demo", "graph ids resolve too"
+ assert store.load_manifest("missing") is None
+ assert store.load_manifest("../etc") is None
+ assert store.graph_id(manifests[0]) == "arch:demo"
+
+
+def test_no_manifest_directory_is_empty(home):
+ assert store.list_manifests() == []
+
+
+# ── Reading models ───────────────────────────────────────────────────────────
+
+
+def test_read_local_model_and_revision_without_git(home, tmp_path):
+ root = _write_service(home, tmp_path)
+ manifest = store.load_manifest("demo")
+ read = store.read_model(manifest, git_runner=lambda _root: "")
+ assert read["source"] == "local" and read["model"]["title"] == "Demo"
+ assert read["revision"].startswith("sha256:"), "no repository → content digest"
+ assert store.read_model(manifest, git_runner=lambda _root: "deadbeef")["revision"] == "deadbeef"
+ (root / "architecture" / "model" / "model.json").unlink()
+ with pytest.raises(store.ArchitectureError) as missing:
+ store.read_model(manifest)
+ assert missing.value.code == 4032 and "compiler" in missing.value.message
+
+
+def test_model_must_be_json_object_with_schema_inside_root(home, tmp_path):
+ root = _write_service(home, tmp_path)
+ manifest = store.load_manifest("demo")
+ (root / "architecture" / "model" / "model.json").write_text("[1,2]", encoding="utf-8")
+ with pytest.raises(store.ArchitectureError, match="schema_version"):
+ store.read_local_model(manifest)
+ (root / "architecture" / "model" / "model.json").write_text("{", encoding="utf-8")
+ with pytest.raises(store.ArchitectureError, match="valid JSON"):
+ store.read_local_model(manifest)
+ manifest["model"] = "architecture/../../outside.json"
+ with pytest.raises(store.ArchitectureError, match="escapes"):
+ store.read_local_model(manifest)
+
+
+def test_read_github_model_uses_raw_url_and_token(home, monkeypatch):
+ manifest = store.normalize_manifest({"name": "P", "description": "d", "repository": "o/r", "ref": "abc"}, "p")
+ seen = {}
+
+ def opener(url, headers):
+ seen["url"] = url
+ seen["headers"] = headers
+ return json.dumps(_model(source_revision="abc123")).encode("utf-8")
+
+ monkeypatch.setenv("GITHUB_TOKEN", "t0k")
+ read = store.read_model(manifest, opener=opener)
+ assert seen["url"] == "https://raw.githubusercontent.com/o/r/abc/architecture/model/model.json"
+ assert seen["headers"]["Authorization"] == "Bearer t0k"
+ assert read == {"model": read["model"], "revision": "abc123", "source": "github"}
+
+ def failing(url, headers):
+ raise OSError("offline")
+
+ with pytest.raises(store.ArchitectureError) as err:
+ store.read_model(manifest, opener=failing)
+ assert err.value.code == 4032 and "offline" in err.value.message
+
+
+# ── Summaries, snapshots, checks ─────────────────────────────────────────────
+
+
+def test_summarize_model_counts_what_portal_shows():
+ summary = store.summarize_model(_model())
+ assert summary == {
+ "schema_version": "1.0.0", "title": "Demo", "source_tree_sha256": DIGEST,
+ "components": 2, "files": 3, "lines": 120, "nodes": 2, "edges": 1, "flows": 1,
+ "invariants": {"total": 2, "holds": 1, "violated": ["two"]},
+ "stores": 1, "externals": 2, "gates": 14, "ratchets": 7, "workflows": 7,
+ }
+ assert store.summarize_model({"schema_version": "1.0.0"})["invariants"] == {"total": 0, "holds": 0, "violated": []}
+ # Portal's compiler names its inventory swift_files/swift_lines; the contract names files/lines. Both count.
+ swift = store.summarize_model(_model(inventory={"swift_files": 9, "swift_lines": 900, "declarations": 1}))
+ assert (swift["files"], swift["lines"]) == (9, 900)
+
+
+def test_snapshots_are_idempotent_and_keep_genesis(home, monkeypatch):
+ monkeypatch.setattr(store, "MAX_SNAPSHOTS", 3)
+ for revision in ("r1", "r2", "r3", "r4", "r5"):
+ store.store_snapshot("demo", revision, _model(title=revision), "local")
+ store.store_snapshot("demo", "r5", _model(title="again"), "local")
+ index = store.list_snapshots("demo")
+ assert index["latest"] == "r5"
+ assert [r["revision"] for r in index["revisions"]] == ["r1", "r4", "r5"], "genesis kept, oldest after it pruned"
+ assert store.load_snapshot("demo", "r1")["title"] == "r1"
+ assert store.load_snapshot("demo", "r2") is None
+ assert store.load_snapshot("demo", "r5")["title"] == "r5", "a known revision is not rewritten"
+ assert index["revisions"][0]["summary"]["components"] == 2
+
+
+def test_run_check_records_pass_fail_and_unavailable(home, tmp_path):
+ _write_service(home, tmp_path, check=["true"])
+ manifest = store.load_manifest("demo")
+
+ class Completed:
+ def __init__(self, code, out=""):
+ self.returncode = code
+ self.stdout = out
+ self.stderr = ""
+
+ passed = store.run_check(manifest, runner=lambda *a, **k: Completed(0, "ok\n"))
+ assert passed["status"] == "passed" and passed["exit_code"] == 0 and passed["output"] == "ok"
+ assert passed["command"] == ["true"] and passed["checked_at"] and "duration_s" in passed
+ failed = store.run_check(manifest, runner=lambda *a, **k: Completed(2, "x" * 5000))
+ assert failed["status"] == "failed" and len(failed["output"]) == store.MAX_CHECK_OUTPUT
+
+ def timeout(*a, **k):
+ raise subprocess.TimeoutExpired(cmd="true", timeout=1)
+
+ timed_out = store.run_check(manifest, runner=timeout, timeout=1)
+ assert timed_out["status"] == "unavailable" and "exceeded" in timed_out["reason"]
+
+ def missing(*a, **k):
+ raise OSError("no such file")
+
+ assert store.run_check(manifest, runner=missing)["status"] == "unavailable"
+ runs = store.list_checks("demo")
+ assert [r["status"] for r in runs] == ["unavailable", "unavailable", "failed", "passed"], "newest first"
+ assert store.last_check("demo")["status"] == "unavailable"
+
+ manifest["check"] = None
+ assert store.run_check(manifest)["reason"].startswith("no check command")
+ github = store.normalize_manifest({"name": "P", "description": "d", "repository": "o/r"}, "gh")
+ assert "repository's CI" in store.run_check(github)["reason"]
+
+
+def test_run_check_really_runs_the_command(home, tmp_path):
+ _write_service(home, tmp_path, check=["python3", "-c", "import sys; print('checked'); sys.exit(3)"])
+ manifest = store.load_manifest("demo")
+ result = store.run_check(manifest, timeout=60)
+ assert result["status"] == "failed" and result["exit_code"] == 3 and "checked" in result["output"]
+
+
+def test_status_and_describe_round_trip(home, tmp_path):
+ root = _write_service(home, tmp_path, check=["true"], source_files=["scripts/x.py"])
+ manifest = store.load_manifest("demo")
+ before = store.status_for(manifest)
+ assert before["ref"] == "arch:demo" and before["source"] == "local" and before["snapshots"] == 0
+ assert "check" not in before
+
+ document = store.describe(manifest, git_runner=lambda _root: "rev1")
+ service = dict(document["service"])
+ [sink] = service.pop("logs")
+ assert sink["id"] == "app" and sink["kind"] == "file" and sink["exists"] is True and sink["path"] == str(root / "logs" / "app.log")
+ assert service == {
+ "id": "arch:demo", "label": "Demo", "description": "A demo service.", "source": "local",
+ "root": str(root), "repository": None, "ref": None, "model_path": store.DEFAULT_MODEL_PATH,
+ "check_configured": True, "runtime": None, "deployments": [],
+ }
+ assert document["revision"] == "rev1" and document["model"]["title"] == "Demo"
+ assert document["summary"]["components"] == 2 and document["check"] is None
+ assert document["contract"]["name"] == "hermes.architecture" and document["contract"]["major"] == 1
+ assert before["contract"] == {"name": "hermes.architecture", "version": "1.0"} and before["conforming"] is True
+ store.run_check(manifest, runner=lambda *a, **k: type("C", (), {"returncode": 0, "stdout": "", "stderr": ""})())
+ after = store.status_for(manifest)
+ assert after["snapshots"] == 1 and after["check"]["status"] == "passed" and after["summary"]["nodes"] == 2
+
+ stored = store.describe(manifest, revision="rev1")
+ assert stored["revision"] == "rev1" and stored["model"]["title"] == "Demo" and stored["check"]["status"] == "passed"
+ with pytest.raises(store.ArchitectureError) as err:
+ store.describe(manifest, revision="nope")
+ assert err.value.code == 4404
diff --git hermes-agent/tests/gateway/test_deployments.py harness/tests/gateway/test_deployments.py
new file mode 100644
index 0000000000000000000000000000000000000000..7ff9d37c90fb3498335d8b46a12b24aee461268e
--- /dev/null
+++ harness/tests/gateway/test_deployments.py
@@ -0,0 +1,326 @@
+"""Deployments: a service's environments off this machine (``tui_gateway/deployments.py``).
+
+Three things are load-bearing:
+
+1. **The declaration is the only thing probed.** Health and revision come from the
+ manifest's own probe (an HTTPS GET or a shell-less command); nothing else is
+ contacted or run, and an unrunnable probe is ``unknown`` with the reason.
+2. **A deployment is a graph node of its own**, one per environment, with the
+ health its probe reports and a ``deploys`` relationship back to the codebase.
+3. **Command log sinks are read once, bounded, never followed** — and only on a
+ deployment; a machine-level manifest cannot declare one.
+"""
+import json
+import logging
+import subprocess
+import sys
+import threading
+from http.server import BaseHTTPRequestHandler, HTTPServer
+from pathlib import Path
+
+import pytest
+
+sys.path.insert(0, str(Path(__file__).parent.parent.parent))
+
+from tests.gateway.architecture_fixtures import local_manifest, minimal_document, write_manifest # noqa: E402
+from tui_gateway import architecture_store as store # noqa: E402
+from tui_gateway import deployments as dep # noqa: E402
+from tui_gateway import methods_service as ms # noqa: E402
+from tui_gateway import service_logs as logs # noqa: E402
+
+
+@pytest.fixture
+def home(tmp_path, monkeypatch):
+ root = tmp_path / ".hermes"
+ monkeypatch.setenv("HERMES_HOME", str(root))
+ dep.reset_cache()
+ yield root
+ dep.reset_cache()
+
+
+@pytest.fixture
+def health_server():
+ """A local HTTP server answering /healthz 200, /down 503, /version with JSON."""
+ class Handler(BaseHTTPRequestHandler):
+ def do_GET(self): # noqa: N802
+ if self.path == "/healthz":
+ body = b"ok"
+ self.send_response(200)
+ elif self.path == "/version":
+ body = json.dumps({"build": {"sha": "9f2c1ab0000", "n": 1}}).encode()
+ self.send_response(200)
+ else:
+ body = b"unavailable"
+ self.send_response(503)
+ self.send_header("Content-Length", str(len(body)))
+ self.end_headers()
+ self.wfile.write(body)
+
+ def log_message(self, *args): # silence
+ return
+
+ server = HTTPServer(("127.0.0.1", 0), Handler)
+ thread = threading.Thread(target=server.serve_forever, daemon=True)
+ thread.start()
+ yield f"http://127.0.0.1:{server.server_address[1]}"
+ server.shutdown()
+
+
+def _deployment(**extra):
+ base = {
+ "id": "prod",
+ "environment": "production",
+ "provider": "aws-lambda",
+ "target": "arn:aws:lambda:us-east-1:1:function:demo",
+ "health": {"kind": "command", "argv": ["true"]},
+ }
+ base.update(extra)
+ return base
+
+
+def _service(tmp_path, service_id="demo", **manifest_extra):
+ root = tmp_path / service_id
+ (root / "architecture" / "model").mkdir(parents=True, exist_ok=True)
+ (root / "architecture" / "model" / "model.json").write_text(json.dumps(minimal_document()), encoding="utf-8")
+ manifest = local_manifest(root, name=service_id.title())
+ manifest.update(manifest_extra)
+ write_manifest(store.manifests_dir(), service_id, manifest)
+ return root, manifest
+
+
+def _handlers(module=ms):
+ pending = dict(module._registry._pending)
+ for fn in pending.values():
+ fn.__globals__["_ok"] = lambda rid, result: {"rid": rid, "result": result}
+ fn.__globals__["_err"] = lambda rid, code, msg: {"rid": rid, "error": {"code": code, "message": msg}}
+ fn.__globals__["_broadcast_global_event"] = lambda event, payload=None: None
+ fn.__globals__.setdefault("logger", logging.getLogger("test"))
+ return pending
+
+
+# ── Declaration ──────────────────────────────────────────────────────────────
+
+
+def test_a_deployment_normalises_with_defaults_and_a_graph_id():
+ (deployment,) = dep.normalize_deployments([_deployment(url="https://demo.example.com", logs=[
+ {"id": "cw", "kind": "command", "argv": "aws logs tail /aws/lambda/demo --since 15m"},
+ ])], "demo")
+ assert deployment["graph_id"] == "deploy:demo/prod"
+ assert deployment["environment"] == "production"
+ assert deployment["health"] == {"kind": "command", "argv": ["true"], "timeout_s": dep.DEFAULT_TIMEOUT_S}
+ assert deployment["revision"] is None
+ assert deployment["logs"][0]["kind"] == "command"
+ assert deployment["logs"][0]["argv"] == ["aws", "logs", "tail", "/aws/lambda/demo", "--since", "15m"]
+ assert deployment["logs"][0]["path"] is None
+
+
+def test_https_probes_normalise_expect_and_refuse_plain_http():
+ (deployment,) = dep.normalize_deployments([_deployment(
+ health={"kind": "https", "url": "https://demo.example.com/healthz", "expect": 204, "timeout_s": 2},
+ revision={"kind": "https", "url": "https://demo.example.com/version", "json_path": "build.sha"},
+ )], "demo")
+ assert deployment["health"] == {"kind": "https", "url": "https://demo.example.com/healthz", "expect": [204], "timeout_s": 2.0}
+ assert deployment["revision"]["json_path"] == "build.sha"
+ with pytest.raises(ValueError, match="https://"):
+ dep.normalize_deployments([_deployment(health={"kind": "https", "url": "http://demo.example.com/healthz"})], "demo")
+
+
+@pytest.mark.parametrize("bad, reason", [
+ ({"id": "Prod"}, "id must match"),
+ ({"provider": "AWS Lambda"}, "provider"),
+ ({"target": ""}, "target is required"),
+ ({"health": None}, "health is required"),
+ ({"health": {"kind": "ping"}}, "health.kind"),
+ ({"health": {"kind": "command", "argv": []}}, "argv"),
+ ({"health": {"kind": "https", "url": "https://x", "expect": 42}}, "expect"),
+ ({"health": {"kind": "command", "argv": ["true"], "timeout_s": -1}}, "timeout_s"),
+ ({"revision": {"kind": "git"}}, "revision.kind"),
+ ({"logs": [{"id": "f", "kind": "launchd_stdout"}]}, "launchd"),
+ ({"logs": [{"id": "c", "kind": "command"}]}, "argv"),
+])
+def test_malformed_deployments_are_rejected(bad, reason):
+ with pytest.raises(ValueError, match=reason):
+ dep.normalize_deployments([_deployment(**bad)], "demo")
+
+
+def test_duplicate_ids_and_non_lists_are_rejected():
+ with pytest.raises(ValueError, match="duplicate"):
+ dep.normalize_deployments([_deployment(), _deployment()], "demo")
+ with pytest.raises(ValueError, match="list"):
+ dep.normalize_deployments({"id": "prod"}, "demo")
+ assert dep.normalize_deployments(None, "demo") == []
+
+
+def test_a_machine_level_manifest_cannot_declare_a_command_sink(tmp_path):
+ with pytest.raises(ValueError, match="only valid on a deployment"):
+ logs.normalize_log_sinks([{"id": "c", "kind": "command", "argv": ["true"]}], None)
+
+
+def test_the_manifest_carries_deployments(home, tmp_path):
+ _service(tmp_path, deployments=[_deployment(url="https://demo.example.com")])
+ manifest = store.load_manifest("demo")
+ assert [d["graph_id"] for d in manifest["deployments"]] == ["deploy:demo/prod"]
+ assert dep.parse_graph_id("deploy:demo/prod") == ("demo", "prod")
+ assert dep.parse_graph_id("deploy:demo") is None and dep.parse_graph_id("arch:demo") is None
+
+
+# ── Probing ──────────────────────────────────────────────────────────────────
+
+
+def test_https_health_is_live_when_the_status_is_expected(health_server):
+ live = dep.probe_health({"kind": "https", "url": f"{health_server}/healthz", "expect": [200], "timeout_s": 2})
+ assert live["status"] == "live" and "→ 200" in live["message"] and live["latency_ms"] >= 0
+ down = dep.probe_health({"kind": "https", "url": f"{health_server}/down", "expect": [200], "timeout_s": 2})
+ assert down["status"] == "down" and "expected 200" in down["message"]
+ unreachable = dep.probe_health({"kind": "https", "url": "http://127.0.0.1:9/healthz", "expect": [200], "timeout_s": 1})
+ assert unreachable["status"] == "down"
+
+
+def test_command_health_follows_the_exit_code_and_a_missing_command_is_unknown():
+ assert dep.probe_health({"kind": "command", "argv": ["true"], "timeout_s": 5})["status"] == "live"
+ down = dep.probe_health({"kind": "command", "argv": ["false"], "timeout_s": 5})
+ assert down["status"] == "down" and down["message"].startswith("exit 1")
+ missing = dep.probe_health({"kind": "command", "argv": ["no-such-binary-xyz"], "timeout_s": 5})
+ assert missing["status"] == "unknown" and "not found" in missing["message"]
+
+
+def test_a_probe_that_hangs_is_down_not_an_exception():
+ def hang(argv, timeout):
+ raise subprocess.TimeoutExpired(argv, timeout)
+ result = dep.probe_health({"kind": "command", "argv": ["sleep", "999"], "timeout_s": 0.5}, runner=hang)
+ assert result["status"] == "down" and "timed out" in result["message"]
+
+
+def test_revision_probes_read_stdout_or_a_json_path(health_server):
+ assert dep.probe_revision({"kind": "command", "argv": ["printf", "9f2c1ab\\nnoise\\n"], "timeout_s": 5})["revision"] == "9f2c1ab"
+ via_json = dep.probe_revision({"kind": "https", "url": f"{health_server}/version", "json_path": "build.sha", "timeout_s": 2})
+ assert via_json["revision"] == "9f2c1ab0000"
+ failed = dep.probe_revision({"kind": "command", "argv": ["false"], "timeout_s": 5})
+ assert failed["revision"] is None and failed["message"].startswith("exit 1")
+
+
+def test_probe_results_are_cached_until_forced(home, tmp_path, monkeypatch):
+ _service(tmp_path, deployments=[_deployment(revision={"kind": "command", "argv": ["echo", "r1"]})])
+ manifest = store.load_manifest("demo")
+ deployment = manifest["deployments"][0]
+ calls = []
+
+ def runner(argv, timeout):
+ calls.append(argv)
+ return subprocess.CompletedProcess(argv, 0, stdout="r1\n", stderr="")
+
+ first = dep.probe_deployment(manifest, deployment, runner=runner)
+ again = dep.probe_deployment(manifest, deployment, runner=runner)
+ assert first["health"]["status"] == "live" and first["revision"]["revision"] == "r1"
+ assert again == first and len(calls) == 2 # health + revision, once
+ dep.probe_deployment(manifest, deployment, force=True, runner=runner)
+ assert len(calls) == 4
+ assert dep.last_probe("deploy:demo/prod")["health"]["status"] == "live"
+
+
+# ── Graph ────────────────────────────────────────────────────────────────────
+
+
+def test_each_deployment_is_a_service_node_related_to_its_codebase(home, tmp_path):
+ _service(tmp_path, deployments=[
+ _deployment(url="https://demo.example.com"),
+ _deployment(id="staging", environment="staging", target="arn:staging", health={"kind": "command", "argv": ["false"]}),
+ ])
+ services = dep.collect_deployment_services()
+ assert [s["id"] for s in services] == ["deploy:demo/prod", "deploy:demo/staging"]
+ prod, staging = services
+ assert prod["label"] == "Demo · production" and prod["health"]["status"] == "live"
+ assert staging["health"]["status"] == "down"
+ assert prod["outputs"] == ["https://demo.example.com"] and staging["outputs"] == []
+ assert prod["relationships"] == [{"predicate": "deploys", "object": "arch:demo"}]
+ assert prod["architecture"]["ref"] == "arch:demo" and prod["architecture"]["deployment"] == "deploy:demo/prod"
+ assert "**live**" in prod["description"] and "aws-lambda" in prod["description"]
+ # The dataflow graph accepts them as service nodes.
+ from cron.jobs import build_cron_graph
+ graph = build_cron_graph(jobs=[], services=services)
+ nodes = {node["id"]: node for node in graph["nodes"]}
+ assert nodes["deploy:demo/prod"]["kind"] == "service"
+ assert nodes["deploy:demo/prod"]["health"]["status"] == "live"
+
+
+def test_the_graph_overlay_includes_deployments(home, tmp_path, monkeypatch):
+ _service(tmp_path, deployments=[_deployment()])
+ import tools.service_graph as graph_mod
+ monkeypatch.setattr(graph_mod, "collect_runtime_services", lambda: [])
+ ids = [s["id"] for s in graph_mod.collect_graph_services()]
+ assert "arch:demo" in ids and "deploy:demo/prod" in ids
+
+
+def test_without_probing_an_unprobed_deployment_is_unknown(home, tmp_path):
+ _service(tmp_path, deployments=[_deployment()])
+ (service,) = dep.collect_deployment_services(probe=False)
+ assert service["health"]["status"] == "unknown" and service["health"]["message"] == "not probed yet"
+
+
+# ── Logs ─────────────────────────────────────────────────────────────────────
+
+
+def test_a_deployment_resolves_its_command_sinks_and_reads_them_once(home, tmp_path):
+ _service(tmp_path, deployments=[_deployment(logs=[
+ {"id": "cw", "kind": "command", "argv": ["printf", "one\\ntwo\\nthree\\n"], "label": "CloudWatch"},
+ ])])
+ sinks = logs.service_sinks("deploy:demo/prod")
+ assert [s["id"] for s in sinks] == ["cw"]
+ resolved = logs.resolve_sink(sinks[0])
+ assert resolved["kind"] == "command" and resolved["exists"] is True and resolved["argv"][0] == "printf"
+ result = logs.read_logs(sinks, "deploy:demo/prod", None, 2, None)
+ assert result["lines"] == ["two", "three"] and result["cursor"] is None and result["truncated"] is True
+ assert result["exit_code"] == 0 and result["sink"]["label"] == "CloudWatch"
+ with pytest.raises(logs.LogError) as exc:
+ logs.start_follow(sinks, "deploy:demo/prod", None, lambda *a: None)
+ assert exc.value.code == 4042
+ with pytest.raises(logs.LogError) as unknown:
+ logs.service_sinks("deploy:demo/nope")
+ assert unknown.value.code == 4050
+ with pytest.raises(logs.LogError) as missing:
+ logs.service_sinks("deploy:ghost/prod")
+ assert missing.value.code == 4030
+
+
+def test_a_failing_or_missing_log_command_is_an_honest_4041():
+ with pytest.raises(logs.LogError, match="not found") as missing:
+ logs.read_command({"id": "cw", "kind": "command", "argv": ["no-such-binary-xyz"]}, 10)
+ assert missing.value.code == 4041
+ with pytest.raises(logs.LogError, match="exited 1"):
+ logs.read_command({"id": "cw", "kind": "command", "argv": ["false"]}, 10)
+
+
+def test_a_deployment_command_sink_satisfies_log_capture(home, tmp_path):
+ _service(tmp_path, logs=[], deployments=[_deployment(logs=[{"id": "cw", "kind": "command", "argv": ["true"]}])])
+ manifest = store.load_manifest("demo")
+ # Capture enforcement is about the local runtime; the deployment's sinks belong
+ # to the deployment and do not stand in for the machine's own logs.
+ assert logs.capture_problem(manifest) == logs.NO_CAPTURE_PROBLEM
+ assert logs.capture_problem({"root": "/x", "logs": manifest["deployments"][0]["logs"]}) is None
+
+
+# ── Methods ──────────────────────────────────────────────────────────────────
+
+
+def test_describe_and_the_service_methods_carry_deployments(home, tmp_path, health_server):
+ _service(tmp_path, deployments=[_deployment(
+ url="https://demo.example.com",
+ health={"kind": "https", "url": f"{health_server}/healthz", "expect": [200], "timeout_s": 2},
+ revision={"kind": "https", "url": f"{health_server}/version", "json_path": "build.sha", "timeout_s": 2},
+ )])
+ handlers = _handlers()
+ listed = handlers["service.deployments"](1, {"service": "demo"})["result"]
+ (before,) = listed["deployments"]
+ assert before["graph_id"] == "deploy:demo/prod" and before["health"] is None and before["revision"] is None
+ probed = handlers["service.deployments.probe"](2, {"service": "arch:demo"})["result"]
+ (after,) = probed["deployments"]
+ assert after["health"]["status"] == "live" and after["revision"] == "9f2c1ab0000" and after["probed_at"]
+ described = store.describe(store.load_manifest("demo"))
+ assert described["service"]["deployments"][0]["health"]["status"] == "live"
+ # A stored revision the live probe answers with is marked live_in that environment.
+ history = store.history(store.load_manifest("demo"))
+ assert all("live_in" not in entry or entry["live_in"] == ["prod"] for entry in history["revisions"])
+ missing = handlers["service.deployments.probe"](3, {"service": "demo", "deployment": "qa"})
+ assert missing["error"]["code"] == 4050
+ unknown = handlers["service.deployments"](4, {"service": "ghost"})
+ assert unknown["error"]["code"] == 4030
diff --git hermes-agent/tests/gateway/test_methods_architecture.py harness/tests/gateway/test_methods_architecture.py
new file mode 100644
index 0000000000000000000000000000000000000000..713a2de2eacb2871674ef1a1f322a2b81ae58c9e
--- /dev/null
+++ harness/tests/gateway/test_methods_architecture.py
@@ -0,0 +1,152 @@
+"""architecture.* handlers, called directly with a fake rid (see test_cron_dataflow.py)."""
+import json
+import logging
+
+import pytest
+
+import tui_gateway.methods_architecture as ma
+from tests.gateway.architecture_fixtures import local_manifest, minimal_document
+from tui_gateway import architecture_store as store
+
+
+@pytest.fixture
+def home(tmp_path, monkeypatch):
+ root = tmp_path / ".hermes"
+ monkeypatch.setenv("HERMES_HOME", str(root))
+ return root
+
+
+@pytest.fixture
+def handlers():
+ """The registered handlers with `_ok`/`_err`/`_broadcast_global_event` stubbed."""
+ pending = dict(ma._registry._pending)
+ events = []
+
+ def _ok(rid, result):
+ return {"rid": rid, "result": result}
+
+ def _err(rid, code, msg):
+ return {"rid": rid, "error": {"code": code, "message": msg}}
+
+ def _broadcast_global_event(event, payload=None):
+ events.append((event, payload))
+
+ for fn in pending.values():
+ fn.__globals__["_ok"] = _ok
+ fn.__globals__["_err"] = _err
+ fn.__globals__["_broadcast_global_event"] = _broadcast_global_event
+ fn.__globals__.setdefault("logger", logging.getLogger("test"))
+ return pending, events
+
+
+def _write_service(tmp_path, check=None):
+ root = tmp_path / "svc"
+ (root / "architecture" / "model").mkdir(parents=True)
+ document = minimal_document()
+ document["components"] = document["components"][:1]
+ for record in document["extraction"]["files"]:
+ record["component"] = "a"
+ for node in document["interplay"]["nodes"] + document["extraction"]["entities"]:
+ node["component"] = "a"
+ (root / "architecture" / "model" / "model.json").write_text(json.dumps(document), encoding="utf-8")
+ manifest = local_manifest(root, description="A demo.")
+ if check:
+ manifest["check"] = check
+ store.manifests_dir().mkdir(parents=True, exist_ok=True)
+ (store.manifests_dir() / "demo.json").write_text(json.dumps(manifest), encoding="utf-8")
+ return root
+
+
+def test_installed_handlers_resolve_every_name_at_runtime(home, tmp_path):
+ """HandlerRegistry.install rebinds each handler onto the *server's* globals, so a
+ helper defined in this module is not visible at runtime (the bug behind
+ "name '_service_param' is not defined"). Install onto a fake server that has
+ exactly the globals server.py provides and call the installed handlers."""
+ import types
+
+ _write_service(tmp_path, check=["python3", "-c", "print('ok')"])
+ fake = types.ModuleType("fake_server")
+ events = []
+ fake._methods = {}
+ fake._ok = lambda rid, result: {"rid": rid, "result": result}
+ fake._err = lambda rid, code, msg: {"rid": rid, "error": {"code": code, "message": msg}}
+ fake._broadcast_global_event = lambda event, payload=None: events.append((event, payload))
+ fake._profile_scoped = lambda fn: fn
+ fake.logger = logging.getLogger("fake")
+ ma.register(fake)
+ assert set(fake._methods) == {"architecture.list", "architecture.describe", "architecture.check", "architecture.history", "architecture.diff"}
+ listed = fake._methods["architecture.list"](1, {})
+ assert listed["result"]["services"][0]["id"] == "arch:demo"
+ described = fake._methods["architecture.describe"](2, {"service": "arch:demo"})
+ assert described["result"]["model"]["title"] == "Demo"
+ assert fake._methods["architecture.describe"](3, {})["error"]["code"] == 4029
+ checked = fake._methods["architecture.check"](4, {"service": "demo"})
+ assert checked["result"]["check"]["status"] == "passed"
+ history = fake._methods["architecture.history"](5, {"service": "arch:demo"})
+ assert history["result"]["latest"] == described["result"]["revision"]
+ assert [e[1]["reason"] for e in events] == ["snapshot", "check"]
+
+
+def test_registry_names_match_docs_and_capabilities():
+ names = {name for name, _ in ma._registry._pending}
+ assert names == {"architecture.list", "architecture.describe", "architecture.check", "architecture.history", "architecture.diff"}
+ capabilities = open("tui_gateway/methods_harness.py", encoding="utf-8").read()
+ for name in names:
+ assert f'"{name}"' in capabilities, f"{name} not advertised by gateway.capabilities"
+ server = open("tui_gateway/server.py", encoding="utf-8").read()
+ for name in names:
+ assert f'"{name}",' in server, f"{name} is not pool-routed (_LONG_HANDLERS)"
+ assert "methods_architecture as _methods_architecture" in server and "_methods_architecture," in server
+ assert "methods_service as _methods_service" in server and "_methods_service," in server
+
+
+def test_list_describe_history_and_check(home, tmp_path, handlers):
+ pending, events = handlers
+ _write_service(tmp_path, check=["python3", "-c", "print('fine')"])
+
+ listed = pending["architecture.list"](1, {})
+ assert listed["rid"] == 1
+ (service,) = listed["result"]["services"]
+ assert service["id"] == "arch:demo" and service["source"] == "local" and service["check_configured"] is True
+ assert service["status"]["ref"] == "arch:demo" and service["status"]["snapshots"] == 0
+
+ described = pending["architecture.describe"](2, {"service": "arch:demo"})
+ document = described["result"]
+ assert document["service"]["id"] == "arch:demo" and document["model"]["title"] == "Demo"
+ assert document["summary"]["components"] == 1
+ assert events == [("architecture.changed", {"service": "arch:demo", "revision": document["revision"], "source": "local", "reason": "snapshot"})]
+
+ # The same revision again: no second announcement, same document.
+ again = pending["architecture.describe"](3, {"service": "demo"})
+ assert again["result"]["revision"] == document["revision"] and len(events) == 1
+
+ stored = pending["architecture.describe"](4, {"service": "arch:demo", "revision": document["revision"]})
+ assert stored["result"]["model"]["title"] == "Demo" and len(events) == 1
+ missing = pending["architecture.describe"](5, {"service": "arch:demo", "revision": "nope"})
+ assert missing["error"]["code"] == 4404
+
+ checked = pending["architecture.check"](6, {"service": "arch:demo"})
+ assert checked["result"]["check"]["status"] == "passed" and "fine" in checked["result"]["check"]["output"]
+ assert events[-1][0] == "architecture.changed" and events[-1][1]["reason"] == "check" and events[-1][1]["status"] == "passed"
+
+ history = pending["architecture.history"](7, {"service": "arch:demo"})
+ result = history["result"]
+ assert result["latest"] == document["revision"]
+ assert [r["revision"] for r in result["revisions"]] == [document["revision"]]
+ assert result["checks"][0]["status"] == "passed"
+
+
+def test_parameter_and_lookup_errors(home, tmp_path, handlers):
+ pending, events = handlers
+ for name in ("architecture.describe", "architecture.check", "architecture.history", "architecture.diff"):
+ assert pending[name](1, {})["error"]["code"] == 4029
+ assert pending[name](1, {"service": " "})["error"]["code"] == 4029
+ assert pending[name](1, {"service": "arch:nobody"})["error"]["code"] == 4030
+ assert pending["architecture.list"](2, {})["result"] == {"services": [], "contract": {"name": "hermes.architecture", "version": "1.0"}}
+ _write_service(tmp_path)
+ (tmp_path / "svc" / "architecture" / "model" / "model.json").unlink()
+ unavailable = pending["architecture.describe"](3, {"service": "arch:demo"})
+ assert unavailable["error"]["code"] == 4032
+ unconfigured = pending["architecture.check"](4, {"service": "arch:demo"})
+ assert unconfigured["result"]["check"]["status"] == "unavailable"
+ assert events == []
diff --git hermes-agent/tests/gateway/test_service_logs.py harness/tests/gateway/test_service_logs.py
new file mode 100644
index 0000000000000000000000000000000000000000..95b55bfb9be05931527e1bb8c2c24d8fc7d1134f
--- /dev/null
+++ harness/tests/gateway/test_service_logs.py
@@ -0,0 +1,501 @@
+"""Service logs: declared and derived sinks by graph id, enforcement, bounded
+tails, follow (tui_gateway/service_logs.py + methods_service.py)."""
+import json
+import logging
+import os
+import plistlib
+
+import pytest
+
+import tui_gateway.methods_service as ms
+from tests.gateway.architecture_fixtures import local_manifest, minimal_document, write_manifest
+from tui_gateway import architecture_store as store
+from tui_gateway import service_logs as logs
+
+
+@pytest.fixture
+def home(tmp_path, monkeypatch):
+ root = tmp_path / ".hermes"
+ monkeypatch.setenv("HERMES_HOME", str(root))
+ return root
+
+
+@pytest.fixture
+def plists(tmp_path, monkeypatch):
+ """A private launchd plist directory the resolver searches instead of the real ones."""
+ folder = tmp_path / "LaunchAgents"
+ folder.mkdir()
+ monkeypatch.setattr(logs, "_LAUNCHD_DIRS", (str(folder),))
+ return folder
+
+
+@pytest.fixture(autouse=True)
+def _no_followers():
+ logs.stop_all("test")
+ yield
+ logs.stop_all("test")
+
+
+def _write_plist(folder, label, out=None, err=None):
+ doc = {"Label": label}
+ if out:
+ doc["StandardOutPath"] = out
+ if err:
+ doc["StandardErrorPath"] = err
+ with open(folder / f"{label}.plist", "wb") as handle:
+ plistlib.dump(doc, handle)
+
+
+def _service(tmp_path, service_id="demo", **manifest_extra):
+ root = tmp_path / service_id
+ (root / "architecture" / "model").mkdir(parents=True, exist_ok=True)
+ (root / "architecture" / "model" / "model.json").write_text(json.dumps(minimal_document()), encoding="utf-8")
+ manifest = local_manifest(root, name=service_id.title())
+ manifest.update(manifest_extra)
+ write_manifest(store.manifests_dir(), service_id, manifest)
+ return root, manifest
+
+
+def _handlers(module=ms):
+ pending = dict(module._registry._pending)
+ events = []
+ for fn in pending.values():
+ fn.__globals__["_ok"] = lambda rid, result: {"rid": rid, "result": result}
+ fn.__globals__["_err"] = lambda rid, code, msg: {"rid": rid, "error": {"code": code, "message": msg}}
+ fn.__globals__["_broadcast_global_event"] = lambda event, payload=None: events.append((event, payload))
+ fn.__globals__.setdefault("logger", logging.getLogger("test"))
+ return pending, events
+
+
+# ── Sink declaration ─────────────────────────────────────────────────────────
+
+
+def test_sinks_of_every_kind_normalise(tmp_path):
+ plist_dir = tmp_path / "agents"
+ plist_dir.mkdir()
+ _write_plist(plist_dir, "demo", out="~/logs/out.log", err="/var/log/demo.err")
+ runtime = {"provider": "launchd", "id": "demo", "graph_id": "launchd:demo"}
+ sinks = logs.normalize_log_sinks([
+ {"id": "app", "kind": "file", "path": "~/app.log", "label": "Application"},
+ {"id": "dir", "kind": "directory", "path": str(tmp_path / "logs")},
+ {"id": "out", "kind": "launchd_stdout"},
+ {"id": "err", "kind": "launchd_stderr"},
+ {"id": "explicit", "kind": "launchd_stdout", "path": "/tmp/explicit.log"},
+ ], runtime, launchd_dirs=[str(plist_dir)])
+ by_id = {s["id"]: s for s in sinks}
+ assert by_id["app"]["label"] == "Application" and by_id["app"]["path"].endswith("/app.log") and "~" not in by_id["app"]["path"]
+ assert by_id["dir"]["label"] == "dir"
+ assert by_id["out"]["path"].endswith("/logs/out.log") and "problem" not in by_id["out"]
+ assert by_id["err"]["path"] == "/var/log/demo.err"
+ assert by_id["explicit"]["path"] == "/tmp/explicit.log", "an explicit path wins over the plist"
+ assert logs.normalize_log_sinks(None, None) == []
+
+
+def test_launchd_sink_without_plist_keeps_the_manifest_but_records_the_problem(tmp_path):
+ runtime = {"provider": "launchd", "id": "ghost", "graph_id": "launchd:ghost"}
+ [sink] = logs.normalize_log_sinks([{"id": "out", "kind": "launchd_stdout"}], runtime, launchd_dirs=[str(tmp_path)])
+ assert sink["path"] is None and "no launchd plist" in sink["problem"]
+ (tmp_path / "ghost.plist").write_bytes(b"not a plist")
+ [sink] = logs.normalize_log_sinks([{"id": "out", "kind": "launchd_stdout"}], runtime, launchd_dirs=[str(tmp_path)])
+ assert sink["path"] is None and "unreadable" in sink["problem"]
+ _write_plist(tmp_path, "quiet")
+ [sink] = logs.normalize_log_sinks([{"id": "out", "kind": "launchd_stdout"}], {**runtime, "id": "quiet"}, launchd_dirs=[str(tmp_path)])
+ assert "declares no StandardOutPath" in sink["problem"]
+
+
+@pytest.mark.parametrize("bad, reason", [
+ ("app.log", "must be a list"),
+ (["app.log"], "must be an object"),
+ ([{"kind": "file", "path": "/x"}], "id must be a non-empty string"),
+ ([{"id": " ", "kind": "file", "path": "/x"}], "id must be a non-empty string"),
+ ([{"id": "a", "kind": "file", "path": "/x"}, {"id": "a", "kind": "file", "path": "/y"}], "duplicate sink id"),
+ ([{"id": "a", "kind": "journal", "path": "/x"}], "kind must be one of"),
+ ([{"id": "a", "kind": "file", "path": "relative/app.log"}], "must be absolute"),
+ ([{"id": "a", "kind": "file"}], "needs a path"),
+ ([{"id": "a", "kind": "file", "path": ""}], "non-empty string"),
+ ([{"id": "a", "kind": "file", "path": "/x", "label": 3}], "label must be a string"),
+ ([{"id": "a", "kind": "launchd_stdout"}], "needs a runtime binding with provider launchd"),
+])
+def test_malformed_sink_declarations_are_rejected(bad, reason):
+ with pytest.raises(ValueError, match=reason):
+ logs.normalize_log_sinks(bad, None)
+ with pytest.raises(ValueError):
+ store.normalize_manifest({"name": "P", "description": "d", "root": "/tmp", "logs": bad}, "p")
+
+
+def test_manifest_carries_sinks_and_github_only_manifests_drop_them(tmp_path, caplog):
+ manifest = store.normalize_manifest({"name": "P", "description": "d", "root": str(tmp_path),
+ "logs": [{"id": "app", "kind": "file", "path": str(tmp_path / "a.log")}]}, "p")
+ assert manifest["logs"] == [{"id": "app", "kind": "file", "label": "app", "path": str(tmp_path / "a.log")}]
+ assert store.normalize_manifest({"name": "P", "description": "d", "root": str(tmp_path)}, "p")["logs"] == []
+ with caplog.at_level(logging.WARNING, logger="tui_gateway.architecture_store"):
+ remote = store.normalize_manifest({"name": "P", "description": "d", "repository": "o/r",
+ "logs": [{"id": "app", "kind": "file", "path": "/x.log"}]}, "p")
+ assert remote["logs"] == [] and "sinks ignored" in caplog.text
+
+
+# ── Enforcement (architecture manifest conformance) ──────────────────────────
+
+
+def test_local_service_without_log_capture_is_not_conforming(home, tmp_path):
+ _service(tmp_path, "quiet", logs=[])
+ manifest = store.load_manifest("quiet")
+ status = store.status_for(manifest)
+ assert status["conforming"] is False and status["problem"] == logs.NO_CAPTURE_PROBLEM
+ assert status["logs"] == []
+ assert store.describe(manifest)["service"]["logs"] == [], "the model itself still serves; the annotation names the gap"
+
+
+def test_declared_sink_makes_the_service_conforming_even_before_the_file_exists(home, tmp_path):
+ _service(tmp_path, "fresh", logs=[{"id": "app", "kind": "file", "path": str(tmp_path / "fresh" / "not-yet.log")}])
+ manifest = store.load_manifest("fresh")
+ assert store.status_for(manifest)["conforming"] is True
+ [sink] = store.describe(manifest)["service"]["logs"]
+ assert sink["exists"] is False and sink["size_bytes"] == 0 and sink["modified_at"] is None
+
+
+def test_unresolvable_launchd_sink_is_not_conforming_and_problems_join(home, tmp_path, plists):
+ root, _ = _service(tmp_path, "svc", runtime={"provider": "launchd", "id": "svc"}, logs=[{"id": "out", "kind": "launchd_stdout"}])
+ manifest = store.load_manifest("svc")
+ status = store.status_for(manifest)
+ assert status["conforming"] is False and "no log sink resolves" in status["problem"] and "no launchd plist" in status["problem"]
+ (root / "architecture" / "model" / "model.json").write_text("{", encoding="utf-8")
+ problem = store.status_for(manifest)["problem"]
+ assert "not valid JSON" in problem and "no log sink resolves" in problem
+
+
+def test_github_manifest_is_exempt_from_log_capture(home):
+ manifest = store.normalize_manifest({"name": "R", "description": "d", "repository": "o/r"}, "remote")
+ assert logs.capture_problem(manifest) is None
+
+
+def test_describe_and_list_carry_resolved_sinks(home, tmp_path):
+ import tui_gateway.methods_architecture as ma
+
+ root, _ = _service(tmp_path)
+ loaded = store.load_manifest("demo")
+ [sink] = store.describe(loaded)["service"]["logs"]
+ assert sink["exists"] is True and sink["size_bytes"] == len("started\n") and sink["modified_at"].endswith("Z")
+ assert sink["path"] == str(root / "logs" / "app.log") and sink["kind"] == "file" and sink["label"] == "app"
+ pending, _ = _handlers(ma)
+ listed = pending["architecture.list"](1, {})["result"]
+ assert listed["services"][0]["logs"][0]["exists"] is True
+ assert listed["services"][0]["status"]["logs"] == ["app"]
+
+
+def test_directory_sink_reads_the_newest_file(tmp_path):
+ folder = tmp_path / "logs"
+ folder.mkdir()
+ older = folder / "a.log"
+ newer = folder / "b.log"
+ older.write_text("old\n")
+ newer.write_text("new\n")
+ os.utime(older, (1_000_000, 1_000_000))
+ os.utime(newer, (2_000_000, 2_000_000))
+ (folder / ".hidden").write_text("x")
+ sink = {"id": "d", "kind": "directory", "path": str(folder)}
+ assert logs.active_file(sink) == newer
+ assert logs.resolve_sink(sink)["path"] == str(newer)
+ empty = tmp_path / "empty"
+ empty.mkdir()
+ resolved = logs.resolve_sink({"id": "e", "kind": "directory", "path": str(empty)})
+ assert resolved["exists"] is False and "no log files yet" in resolved["problem"]
+
+
+# ── Resolution by graph id ───────────────────────────────────────────────────
+
+
+def test_arch_service_resolves_its_declared_sinks(home, tmp_path):
+ root, _ = _service(tmp_path)
+ sinks = logs.service_sinks("arch:demo")
+ assert [s["id"] for s in sinks] == ["app"] and sinks[0]["path"] == str(root / "logs" / "app.log")
+ with pytest.raises(logs.LogError) as exc:
+ logs.service_sinks("arch:nobody")
+ assert exc.value.code == 4030
+
+
+def test_bound_arch_service_unions_the_plist_sinks(home, tmp_path, plists):
+ out = tmp_path / "out.log"
+ err = tmp_path / "err.log"
+ out.write_text("o\n")
+ _write_plist(plists, "cam", out=str(out), err=str(err))
+ _service(tmp_path, "cam", runtime={"provider": "launchd", "id": "cam"})
+ sinks = logs.service_sinks("arch:cam")
+ assert [(s["id"], s["kind"]) for s in sinks] == [("app", "file"), ("launchd_stdout", "launchd_stdout"), ("launchd_stderr", "launchd_stderr")]
+ assert sinks[1]["path"] == str(out) and sinks[2]["path"] == str(err)
+ # A declared sink with the derived id, or the same (kind, path), is not duplicated.
+ _service(tmp_path, "cam2", runtime={"provider": "launchd", "id": "cam"},
+ logs=[{"id": "launchd_stdout", "kind": "launchd_stdout"}, {"id": "mine", "kind": "launchd_stderr", "path": str(err)}])
+ assert [s["id"] for s in logs.service_sinks("arch:cam2")] == ["launchd_stdout", "mine"]
+
+
+def test_launchd_service_resolves_plist_sinks_and_unions_a_bound_manifest(home, tmp_path, plists):
+ out = tmp_path / "out.log"
+ out.write_text("o\n")
+ _write_plist(plists, "cam", out=str(out))
+ assert [(s["id"], s["kind"], s["path"]) for s in logs.service_sinks("launchd:cam")] == [("stdout", "launchd_stdout", str(out))]
+ root, _ = _service(tmp_path, "cam", runtime={"provider": "launchd", "id": "cam"})
+ sinks = logs.service_sinks("launchd:cam")
+ assert [s["id"] for s in sinks] == ["stdout", "app"] and sinks[1]["path"] == str(root / "logs" / "app.log")
+ assert logs.service_sinks("launchd:unknown") == [], "no plist and no manifest: nothing to read"
+ with pytest.raises(logs.LogError) as exc:
+ logs.select_sink([], None, "launchd:unknown")
+ assert exc.value.code == 4040
+
+
+@pytest.mark.parametrize("graph_id", ["docker:0123456789ab", "nomad:dashboard", "proc_0123456789ab"])
+def test_unsupported_providers_are_an_honest_4042(home, graph_id):
+ with pytest.raises(logs.LogError) as exc:
+ logs.service_sinks(graph_id)
+ assert exc.value.code == 4042 and logs.UNSUPPORTED_PROVIDER_PROBLEM in exc.value.message
+
+
+def test_non_graph_ids_are_rejected(home):
+ for bad in ("https://example", "launchd:", "demo"):
+ with pytest.raises(logs.LogError) as exc:
+ logs.service_sinks(bad)
+ assert exc.value.code == 4001, bad
+
+
+# ── Reads ────────────────────────────────────────────────────────────────────
+
+
+def _lines(n, prefix="line"):
+ return "".join(f"{prefix} {i}\n" for i in range(n))
+
+
+def test_tail_returns_the_last_complete_lines_and_a_cursor(tmp_path):
+ path = tmp_path / "app.log"
+ path.write_text(_lines(10) + "partial")
+ result = logs.read_tail(path, 3)
+ assert result["lines"] == ["line 7", "line 8", "line 9"]
+ assert int(result["cursor"]) == len(_lines(10)) and result["truncated"] is True
+ everything = logs.read_tail(path, 50)
+ assert everything["lines"] == [f"line {i}" for i in range(10)] and everything["truncated"] is False
+ (tmp_path / "nolines.log").write_text("no newline yet")
+ assert logs.read_tail(tmp_path / "nolines.log", 5) == {"lines": [], "cursor": "0", "truncated": False, "scanned_from": 0}
+
+
+def test_tail_scan_is_bounded(tmp_path, monkeypatch):
+ monkeypatch.setattr(logs, "TAIL_SCAN_BYTES", 64)
+ path = tmp_path / "big.log"
+ path.write_text(_lines(200))
+ result = logs.read_tail(path, 1000)
+ assert result["truncated"] is True and result["lines"][-1] == "line 199"
+ assert all(line.startswith("line ") for line in result["lines"]), "the half-scanned first line is dropped"
+ assert int(result["cursor"]) == path.stat().st_size
+
+
+def test_cursor_reads_only_what_was_appended(tmp_path):
+ path = tmp_path / "app.log"
+ path.write_text(_lines(3))
+ first = logs.read_tail(path, 10)
+ with open(path, "a") as handle:
+ handle.write("line 3\nline 4\nhalf")
+ since = logs.read_since(path, int(first["cursor"]), 10)
+ assert since["lines"] == ["line 3", "line 4"] and since["truncated"] is False
+ assert int(since["cursor"]) == len(_lines(5))
+ again = logs.read_since(path, int(since["cursor"]), 10)
+ assert again["lines"] == [] and again["cursor"] == since["cursor"]
+ with open(path, "a") as handle:
+ handle.write("-done\n")
+ assert logs.read_since(path, int(again["cursor"]), 10)["lines"] == ["half-done"]
+
+
+def test_cursor_read_is_bounded_and_resumable(tmp_path):
+ path = tmp_path / "app.log"
+ path.write_text(_lines(7))
+ page = logs.read_since(path, 0, 3)
+ assert page["lines"] == ["line 0", "line 1", "line 2"] and page["truncated"] is True
+ rest = logs.read_since(path, int(page["cursor"]), 10)
+ assert rest["lines"] == ["line 3", "line 4", "line 5", "line 6"] and rest["truncated"] is False
+
+
+def test_rotation_restarts_from_the_tail(tmp_path):
+ path = tmp_path / "app.log"
+ path.write_text(_lines(50))
+ cursor = int(logs.read_tail(path, 5)["cursor"])
+ path.write_text(_lines(2, "fresh"))
+ result = logs.read_since(path, cursor, 5)
+ assert result["rotated"] is True and result["lines"] == ["fresh 0", "fresh 1"]
+
+
+def test_undecodable_bytes_are_replaced_not_fatal(tmp_path):
+ path = tmp_path / "app.log"
+ path.write_bytes(b"ok\n\xff\xfe bad\n")
+ assert logs.read_tail(path, 5)["lines"] == ["ok", "�� bad"]
+
+
+def test_param_parsing():
+ assert logs.parse_lines(None) == logs.DEFAULT_LINES and logs.parse_lines(7) == 7
+ for bad in (0, logs.MAX_LINES + 1, "5", True, 2.5):
+ with pytest.raises(logs.LogError) as exc:
+ logs.parse_lines(bad)
+ assert exc.value.code == 4001
+ assert logs.parse_cursor(None) is None and logs.parse_cursor("") is None and logs.parse_cursor("12") == 12 and logs.parse_cursor(3) == 3
+ for bad in ("x", -1, True, 1.5):
+ with pytest.raises(logs.LogError):
+ logs.parse_cursor(bad)
+
+
+# ── RPC ──────────────────────────────────────────────────────────────────────
+
+
+def test_logs_rpc_tails_and_continues(home, tmp_path):
+ root, _ = _service(tmp_path)
+ (root / "logs" / "app.log").write_text(_lines(5))
+ pending, _ = _handlers()
+ result = pending["service.logs"](1, {"service": "arch:demo", "lines": 2})["result"]
+ assert result["service"] == "arch:demo" and result["lines"] == ["line 3", "line 4"] and result["truncated"] is True
+ assert result["sink"]["id"] == "app" and result["sink"]["exists"] is True and result["encoding"] == "utf-8-replace"
+ assert [s["id"] for s in result["sinks"]] == ["app"]
+ with open(root / "logs" / "app.log", "a") as handle:
+ handle.write("line 5\n")
+ more = pending["service.logs"](2, {"service": "arch:demo", "sink": "app", "cursor": result["cursor"]})["result"]
+ assert more["lines"] == ["line 5"] and "rotated" not in more
+
+
+def test_logs_rpc_reads_a_launchd_node(home, tmp_path, plists):
+ out = tmp_path / "out.log"
+ out.write_text("boot\nready\n")
+ _write_plist(plists, "cam", out=str(out))
+ pending, _ = _handlers()
+ result = pending["service.logs"](1, {"service": "launchd:cam"})["result"]
+ assert result["service"] == "launchd:cam" and result["sink"]["id"] == "stdout" and result["lines"] == ["boot", "ready"]
+
+
+def test_logs_rpc_errors(home, tmp_path):
+ _service(tmp_path)
+ _service(tmp_path, "quiet", logs=[])
+ _service(tmp_path, "fresh", logs=[{"id": "app", "kind": "file", "path": str(tmp_path / "fresh" / "nope.log")}])
+ pending, _ = _handlers()
+ call = pending["service.logs"]
+ assert call(1, {})["error"]["code"] == 4029
+ assert call(2, {"service": "arch:nobody"})["error"]["code"] == 4030
+ assert call(3, {"service": "arch:demo", "sink": "ghost"})["error"]["code"] == 4040
+ assert call(4, {"service": "arch:quiet"})["error"]["code"] == 4040
+ assert call(5, {"service": "arch:fresh"})["error"]["code"] == 4041
+ assert call(6, {"service": "arch:demo", "lines": 0})["error"]["code"] == 4001
+ assert call(7, {"service": "arch:demo", "cursor": "abc"})["error"]["code"] == 4001
+ assert call(8, {"service": "docker:0123456789ab"})["error"]["code"] == 4042
+ assert call(9, {"service": "not-a-graph-id"})["error"]["code"] == 4001
+
+
+def test_only_resolved_sinks_are_ever_read(home, tmp_path):
+ _service(tmp_path)
+ secret = tmp_path / "secret.txt"
+ secret.write_text("nope\n")
+ pending, _ = _handlers()
+ assert pending["service.logs"](1, {"service": "arch:demo", "sink": str(secret)})["error"]["code"] == 4040
+
+
+# ── Follow ───────────────────────────────────────────────────────────────────
+
+
+def test_follow_broadcasts_appended_lines_and_stops(home, tmp_path):
+ root, _ = _service(tmp_path)
+ sinks = logs.service_sinks("arch:demo")
+ events = []
+ clock = {"now": 100.0}
+ follower = logs.start_follow(sinks, "arch:demo", None, lambda e, p: events.append((e, p)), spawn=False, clock=lambda: clock["now"])
+ assert follower.cursor == (root / "logs" / "app.log").stat().st_size, "following starts at the current end"
+ assert follower.poll_once() is None and events == []
+ with open(root / "logs" / "app.log", "a") as handle:
+ handle.write("one\ntwo\npartial")
+ payload = follower.poll_once()
+ assert payload["lines"] == ["one", "two"] and payload["service"] == "arch:demo" and payload["sink"] == "app"
+ assert events == [("service.log", payload)]
+ assert follower.poll_once() is None, "a partial line waits for its newline"
+ same = logs.start_follow(sinks, "arch:demo", "app", lambda e, p: None, spawn=False)
+ assert same is follower and logs.following("arch:demo", "app") is follower
+ (root / "logs" / "app.log").write_text("fresh\n")
+ rotated = follower.poll_once()
+ assert rotated["rotated"] is True and rotated["lines"] == ["fresh"]
+ assert logs.stop_follow("arch:demo", "app") is True
+ assert events[-1][1]["stopped"] == "stopped" and logs.following("arch:demo", "app") is None
+ assert logs.stop_follow("arch:demo", "app") is False
+
+
+def test_follow_idle_timeout(home, tmp_path):
+ _service(tmp_path)
+ sinks = logs.service_sinks("arch:demo")
+ events = []
+ clock = {"now": 0.0}
+ follower = logs.start_follow(sinks, "arch:demo", None, lambda e, p: events.append((e, p)), spawn=False, clock=lambda: clock["now"])
+ sleeps = []
+
+ def sleep(seconds):
+ sleeps.append(seconds)
+ clock["now"] += logs.FOLLOW_IDLE_S / 2 + 1
+
+ follower.run(interval=1.0, sleep=sleep)
+ assert follower.stop_requested.is_set() and events[-1][1]["stopped"] == "idle-timeout"
+ assert len(sleeps) == 2 and logs.following("arch:demo", "app") is None
+ clock["now"] = 0.0
+ follower = logs.start_follow(sinks, "arch:demo", None, lambda e, p: None, spawn=False, clock=lambda: clock["now"])
+ clock["now"] = logs.FOLLOW_IDLE_S - 1
+ follower.touch()
+ assert follower.idle_for() == 0.0
+
+
+def test_follow_rpc(home, tmp_path):
+ root, _ = _service(tmp_path)
+ _service(tmp_path, "fresh", logs=[{"id": "app", "kind": "file", "path": str(tmp_path / "fresh" / "nope.log")}])
+ pending, events = _handlers()
+ follow = pending["service.logs.follow"]
+ assert follow(1, {})["error"]["code"] == 4029
+ assert follow(2, {"service": "arch:nobody"})["error"]["code"] == 4030
+ assert follow(3, {"service": "arch:demo", "enabled": "yes"})["error"]["code"] == 4001
+ assert follow(4, {"service": "arch:demo", "sink": "ghost"})["error"]["code"] == 4040
+ assert follow(5, {"service": "arch:fresh"})["error"]["code"] == 4041
+ assert follow(6, {"service": "nomad:x"})["error"]["code"] == 4042
+ started = follow(7, {"service": "arch:demo"})["result"]
+ assert started == {"service": "arch:demo", "following": True, "sink": "app", "cursor": str((root / "logs" / "app.log").stat().st_size)}
+ follower = logs.following("arch:demo", "app")
+ assert follower is not None and follower.thread is not None and follower.thread.daemon
+ with open(root / "logs" / "app.log", "a") as handle:
+ handle.write("hello\n")
+ assert follower.poll_once()["lines"] == ["hello"]
+ assert events[-1] == ("service.log", {"service": "arch:demo", "sink": "app", "lines": ["hello"], "cursor": str((root / "logs" / "app.log").stat().st_size)})
+ stopped = follow(8, {"service": "arch:demo", "enabled": False})["result"]
+ assert stopped == {"service": "arch:demo", "following": False, "sink": "app", "stopped": True}
+ assert events[-1][1]["stopped"] == "stopped"
+ assert follow(9, {"service": "arch:demo", "enabled": False})["result"]["stopped"] is False
+
+
+def test_installed_handlers_resolve_every_name_at_runtime(home, tmp_path):
+ import types
+
+ _service(tmp_path)
+ fake = types.ModuleType("fake_server")
+ fake._methods = {}
+ fake._ok = lambda rid, result: {"rid": rid, "result": result}
+ fake._err = lambda rid, code, msg: {"rid": rid, "error": {"code": code, "message": msg}}
+ fake._broadcast_global_event = lambda event, payload=None: None
+ fake._profile_scoped = lambda fn: fn
+ fake.logger = logging.getLogger("fake")
+ ms.register(fake)
+ assert set(fake._methods) == {"service.logs", "service.logs.follow", "service.deployments", "service.deployments.probe"}
+ assert fake._methods["service.logs"](1, {"service": "arch:demo"})["result"]["lines"] == ["started"]
+ assert fake._methods["service.logs.follow"](2, {"service": "arch:demo"})["result"]["following"] is True
+ assert fake._methods["service.logs.follow"](3, {"service": "arch:demo", "enabled": False})["result"]["stopped"] is True
+ server = open("tui_gateway/server.py", encoding="utf-8").read()
+ assert "methods_service as _methods_service" in server and "_methods_service," in server
+ assert '"service.logs",' in server and '"service.logs.follow",' in server, "both run on the RPC pool"
+
+
+def test_capabilities_advertise_service_logs():
+ import tui_gateway.methods_harness as mh
+
+ pending = dict(mh._registry._pending)
+ fn = pending["gateway.capabilities"]
+ fn.__globals__["_ok"] = lambda rid, result: {"result": result}
+ fn.__globals__.setdefault("logger", logging.getLogger("test"))
+ result = fn(1, {})["result"]
+ assert result["service"] == {"methods": ["service.logs", "service.logs.follow", "service.deployments", "service.deployments.probe"], "events": ["service.log"]}
+ assert "service.deployments.probe" in result["capability_names"]
+ assert "service.logs" in result["capability_names"] and "service.logs.follow" in result["capability_names"]
+ assert result["architecture"]["methods"] == [
+ "architecture.list", "architecture.describe", "architecture.check", "architecture.history", "architecture.diff",
+ ]
+ assert result["architecture"]["events"] == ["architecture.changed"]
diff --git hermes-agent/tools/architecture_services.py harness/tools/architecture_services.py
new file mode 100644
index 0000000000000000000000000000000000000000..c173372025374b6b92d11519149d5b8a7450e972
--- /dev/null
+++ harness/tools/architecture_services.py
@@ -0,0 +1,91 @@
+"""Architecture-manifest services for the cron interflow graph.
+
+A service that conforms to the architecture standard (see
+``tui_gateway/architecture_store.py``) is declared by a manifest under
+``~/.hermes/services/architecture/<id>.json``. This module turns each manifest
+into an **architecture definition**: the standalone service declaration the
+graph would draw for a codebase nobody else reports (``arch:<id>``), its code
+(``source_files``), the ``architecture`` annotation Portal opens the model from
+and, when the manifest binds to a runtime service, the canonical graph id of
+that service. ``tools/service_graph.py`` composes the definitions with the
+process, Docker, Nomad and launchd providers: a bound definition annotates the
+runtime node, a standalone one is a node of its own. There is nothing to probe
+here — a manifest describes a codebase, not a running process.
+"""
+from __future__ import annotations
+
+import logging
+from pathlib import Path
+from typing import Any, Dict, List, Optional
+
+logger = logging.getLogger(__name__)
+
+
+def _absolute_source_files(manifest: Dict[str, Any]) -> List[str]:
+ """Manifest ``source_files`` are relative to the service root; the graph's
+ resolver treats relative paths as ``~/.hermes/scripts`` entries, so make them
+ absolute here. The model file itself is always listed so it is browsable."""
+ root = manifest.get("root")
+ if not root:
+ return []
+ base = Path(root)
+ files = [str(base / manifest["model"])]
+ for item in manifest.get("source_files") or []:
+ path = Path(item).expanduser()
+ files.append(str(path if path.is_absolute() else base / path))
+ return files
+
+
+def collect_architecture_definitions(home: Optional[str] = None) -> List[Dict[str, Any]]:
+ """Every valid manifest as a definition, sorted by manifest id. Fail-open per manifest."""
+ from cron.jobs import normalize_service_declaration
+ from tui_gateway import architecture_store as store
+
+ definitions: List[Dict[str, Any]] = []
+ for manifest in store.list_manifests(home):
+ try:
+ declaration = normalize_service_declaration(
+ manifest["name"],
+ manifest["description"],
+ inputs=manifest.get("inputs"),
+ outputs=manifest.get("outputs"),
+ side_effects=manifest.get("side_effects"),
+ relationships=manifest.get("relationships"),
+ source_files=_absolute_source_files(manifest),
+ )
+ except ValueError as exc:
+ logger.warning("architecture manifest %s rejected: %s", manifest["id"], exc)
+ continue
+ annotation = store.status_for(manifest, home)
+ service: Dict[str, Any] = {
+ "id": store.graph_id(manifest),
+ "label": declaration["name"],
+ "description": declaration["description"],
+ "inputs": declaration["inputs"],
+ "outputs": declaration["outputs"],
+ "side_effects": declaration["side_effects"],
+ "source_files": declaration["source_files"],
+ "architecture": annotation,
+ }
+ if declaration.get("relationships"):
+ service["relationships"] = declaration["relationships"]
+ definitions.append({
+ "manifest_id": manifest["id"],
+ "graph_id": store.graph_id(manifest),
+ "runtime": manifest.get("runtime"),
+ "service": service,
+ "source_files": declaration["source_files"],
+ "architecture": annotation,
+ })
+ return definitions
+
+
+def collect_architecture_services(home: Optional[str] = None) -> List[Dict[str, Any]]:
+ """The standalone definitions as service declarations — codebases no runtime
+ provider reports. Bound definitions are not services of their own; they
+ annotate the runtime node through ``tools.service_graph.attach_architecture``."""
+ return [
+ definition["service"]
+ for definition in collect_architecture_definitions(home)
+ if not definition.get("runtime")
+ ]
diff --git hermes-agent/tools/service_graph.py harness/tools/service_graph.py
new file mode 100644
index 0000000000000000000000000000000000000000..0872a92bfa42c8c9b00b133aceee4efeb251901f
--- /dev/null
+++ harness/tools/service_graph.py
@@ -0,0 +1,226 @@
+"""The services the dataflow graph draws: runtime providers, then architecture.
+
+Four liveness providers put running services on the graph — tracked background
+processes, Docker containers, Nomad jobs, launchd services. Architecture
+manifests (``tui_gateway/architecture_store.py``) add the SDLC side: a model, a
+check, a history. The two meet here, after every collector has run and before
+``build_cron_graph`` turns declarations into nodes:
+
+* a manifest **bound** to a runtime service (``"runtime": {"provider", "id"}``)
+ annotates that provider's node — one node per logical service, with the
+ provider's liveness and topology and the manifest's ``architecture`` and
+ source files — and adds no node of its own;
+* a manifest with no binding is a **standalone** codebase and keeps its own
+ ``arch:<id>`` node, as before;
+* a manifest's **deployments** (``tui_gateway/deployments.py``) are one node each
+ (``deploy:<id>/<env>``) with the health their declared probe reports, related
+ to the codebase node by ``deploys``.
+Composition is exact (canonical graph ids, never display names), deterministic,
+and fail-open: a binding whose runtime is absent, or two manifests binding one
+runtime, is logged and skipped rather than fabricating or overwriting a node.
+"""
+from __future__ import annotations
+
+import copy
+import logging
+import os
+import threading
+import time
+from concurrent.futures import ThreadPoolExecutor, as_completed
+from typing import Any, Callable, Dict, Iterable, List, Optional
+
+logger = logging.getLogger(__name__)
+
+# ``cron.graph`` is polled — Portal asks every 60 s from every open surface, and
+# the Desktop / TUI clients do the same — and every call used to re-run the
+# four runtime probes (``docker ps``, ``nomad job status``, ``launchctl list``,
+# the process registry), each a shell-out that takes seconds on a loaded host.
+# The probes are cached for a short TTL so overlapping polls share one round.
+# The TTL is read per call so a running gateway can be tuned without a restart;
+# 0 (or a non-number) disables the cache and restores the old always-probe path.
+_RUNTIME_CACHE_TTL_ENV = "HERMES_SERVICE_GRAPH_TTL"
+_RUNTIME_CACHE_TTL_DEFAULT = 10.0
+_runtime_cache_lock = threading.Lock()
+_runtime_cache: Dict[str, Any] = {"at": None, "services": None}
+
+
+def runtime_cache_ttl() -> float:
+ """Seconds a runtime-probe result is reused; ``0`` disables the cache."""
+ raw = os.environ.get(_RUNTIME_CACHE_TTL_ENV)
+ if raw is None or not raw.strip():
+ return _RUNTIME_CACHE_TTL_DEFAULT
+ try:
+ return max(0.0, float(raw))
+ except ValueError:
+ return 0.0
+
+
+def reset_runtime_cache() -> None:
+ """Forget the cached probe result (tests, and callers that just changed a service)."""
+ with _runtime_cache_lock:
+ _runtime_cache["at"] = None
+ _runtime_cache["services"] = None
+
+
+def _runtime_collectors() -> Dict[str, Callable[[], List[Dict[str, Any]]]]:
+ from tools.docker_services import collect_docker_services
+ from tools.launchd_services import collect_launchd_services
+ from tools.nomad_services import collect_nomad_services
+ from tools.process_registry import process_registry
+
+ return {
+ "process": process_registry.collect_service_declarations,
+ "docker": collect_docker_services,
+ "nomad": collect_nomad_services,
+ "launchd": collect_launchd_services,
+ }
+
+
+def collect_runtime_services(
+ collectors: Optional[Dict[str, Callable[[], List[Dict[str, Any]]]]] = None,
+) -> List[Dict[str, Any]]:
+ """Every live service the providers report. Providers run concurrently and
+ fail open: one provider's hiccup must never sink the graph. Results are
+ ordered by provider name so the graph is stable across calls."""
+ collectors = collectors if collectors is not None else _runtime_collectors()
+ results: Dict[str, List[Dict[str, Any]]] = {}
+ if not collectors:
+ return []
+ with ThreadPoolExecutor(max_workers=len(collectors)) as executor:
+ pending = {executor.submit(fn): name for name, fn in collectors.items()}
+ for future in as_completed(pending):
+ provider = pending[future]
+ try:
+ results[provider] = list(future.result() or [])
+ except Exception:
+ logger.exception("service overlay unavailable: %s", provider)
+ results[provider] = []
+ services: List[Dict[str, Any]] = []
+ for provider in sorted(results):
+ services.extend(results[provider])
+ return services
+
+
+def _merged_source_files(*lists: Iterable[str]) -> List[str]:
+ """Deterministic union of source-file paths, deduplicated by normalized path."""
+ import os
+
+ seen: Dict[str, str] = {}
+ for values in lists:
+ for value in values or []:
+ if not isinstance(value, str) or not value.strip():
+ continue
+ key = os.path.normpath(value.strip())
+ seen.setdefault(key, value.strip())
+ return [seen[key] for key in sorted(seen)]
+
+
+def attach_architecture(
+ runtime_services: List[Dict[str, Any]],
+ definitions: List[Dict[str, Any]],
+) -> List[Dict[str, Any]]:
+ """Compose runtime services with architecture definitions.
+
+ ``definitions`` come from :func:`tools.architecture_services.collect_architecture_definitions`:
+ each has ``service`` (the standalone declaration), ``source_files``,
+ ``architecture`` (the node annotation) and, when bound, ``runtime`` with the
+ canonical ``graph_id``. Runtime declarations are returned first, in their
+ given order, with bound annotations merged in; standalone definitions
+ follow, sorted by id. Runtime-owned facts (health, inputs, outputs,
+ side_effects, relationships, description) stay authoritative; the manifest
+ contributes only ``architecture`` and its source files.
+ """
+ by_id: Dict[str, Dict[str, Any]] = {}
+ ordered: List[Dict[str, Any]] = []
+ for service in runtime_services:
+ sid = service.get("id")
+ if not isinstance(sid, str) or not sid:
+ continue
+ copy = dict(service)
+ by_id[sid] = copy
+ ordered.append(copy)
+
+ bound: Dict[str, List[Dict[str, Any]]] = {}
+ standalone: List[Dict[str, Any]] = []
+ for definition in definitions:
+ runtime = definition.get("runtime")
+ if isinstance(runtime, dict) and runtime.get("graph_id"):
+ bound.setdefault(str(runtime["graph_id"]), []).append(definition)
+ else:
+ standalone.append(definition)
+
+ for target in sorted(bound):
+ candidates = bound[target]
+ if len(candidates) > 1:
+ names = ", ".join(sorted(str(d.get("manifest_id")) for d in candidates))
+ logger.warning(
+ "architecture: %d manifests bind runtime service %s (%s); none applied — one manifest per runtime service",
+ len(candidates), target, names,
+ )
+ continue
+ definition = candidates[0]
+ service = by_id.get(target)
+ if service is None:
+ logger.warning(
+ "architecture manifest %s binds runtime service %s, which no provider reports right now; "
+ "the model stays reachable via architecture.describe but nothing is drawn for it",
+ definition.get("manifest_id"), target,
+ )
+ continue
+ service["architecture"] = dict(definition.get("architecture") or {})
+ service["source_files"] = _merged_source_files(service.get("source_files") or [], definition.get("source_files") or [])
+
+ for definition in sorted(standalone, key=lambda d: str(d.get("service", {}).get("id", ""))):
+ service = definition.get("service")
+ if isinstance(service, dict) and service.get("id"):
+ ordered.append(dict(service))
+ return ordered
+
+
+def _cached_runtime_services() -> List[Dict[str, Any]]:
+ """``collect_runtime_services`` behind the TTL cache.
+
+ The lock is held across the probe on purpose: concurrent ``cron.graph``
+ calls (several surfaces polling at once, now dispatched concurrently by the
+ WebSocket server) wait for the one in-flight round instead of each starting
+ their own. Callers get a deep copy so ``attach_architecture`` /
+ ``build_cron_graph`` can decorate the dicts without leaking into the cache.
+ """
+ ttl = runtime_cache_ttl()
+ if ttl <= 0:
+ return collect_runtime_services()
+ with _runtime_cache_lock:
+ now = time.monotonic()
+ at = _runtime_cache["at"]
+ if at is not None and now - at < ttl and _runtime_cache["services"] is not None:
+ return copy.deepcopy(_runtime_cache["services"])
+ services = collect_runtime_services()
+ _runtime_cache["at"] = time.monotonic()
+ _runtime_cache["services"] = copy.deepcopy(services)
+ return services
+
+
+def collect_graph_services() -> List[Dict[str, Any]]:
+ """What ``cron.graph`` / ``code.graph`` overlay on the dataflow graph."""
+ from tools.architecture_services import collect_architecture_definitions
+
+ # Only the runtime probes are cached. Architecture attachment reads a
+ # handful of small JSON manifests from disk (architecture_store.list_manifests
+ # + status_for) — milliseconds, no subprocess or network — and leaving it
+ # uncached means a manifest written or checked a moment ago shows up on the
+ # very next graph poll rather than after the TTL.
+ runtime = _cached_runtime_services()
+ try:
+ definitions = collect_architecture_definitions()
+ except Exception:
+ logger.exception("service overlay unavailable: architecture")
+ definitions = []
+ services = attach_architecture(runtime, definitions)
+ # Deployments: one node per declared environment off this machine, with the
+ # health its own probe reports. They are never bound to a local runtime.
+ try:
+ from tui_gateway.deployments import collect_deployment_services
+ services.extend(collect_deployment_services())
+ except Exception:
+ logger.exception("service overlay unavailable: deployments")
+ return services
diff --git hermes-agent/tui_gateway/architecture_contract.py harness/tui_gateway/architecture_contract.py
new file mode 100644
index 0000000000000000000000000000000000000000..63a58ee06a930a44ff01a6dddc4af8daaf08d4be
--- /dev/null
+++ harness/tui_gateway/architecture_contract.py
@@ -0,0 +1,522 @@
+"""The hermes.architecture document contract, version 1.
+
+This file is the contract between a service's architecture compiler, the Harness
+gateway that validates and serves the document (`architecture.describe`), and
+every renderer of it (Portal natively, the static observatory on the web). It is
+vendored byte-for-byte into each repository that speaks the contract and pinned
+by digest there, so a change to the contract is a change in every repository at
+once, on record, rather than a drift one side discovers at decode time.
+
+What the contract fixes:
+
+ * The document is JSON with a semver `schema_version`; the major number is the
+ contract major. A consumer that supports major 1 accepts every 1.x document.
+ * Five sections are REQUIRED: `components`, `interplay` (the system map),
+ `extraction` (where every construction on the map was extracted from),
+ `ci` (the gates that defend the model) and `inventory`, plus
+ `evidence_metadata`. A service either proves where its map came from and
+ what defends it, or it is not a conforming service. `stores`, `externals`,
+ `layers`, `edges` and `behavior` are optional.
+ * Identifiers are unique and every reference resolves: edges to nodes, flow
+ steps to edges, entities to nodes (one-to-one: every construction has a
+ provenance), origins to files and passes, gate wiring to jobs, the merge
+ gate to at least one job.
+ * Unknown fields are allowed everywhere (a 1.x minor may add them); unknown
+ enum values are rejected only where the renderers branch on them.
+
+The validator is deliberately dependency-free (no jsonschema) so both
+repositories run the identical code in CI. `SCHEMA` is also exportable as a JSON
+Schema (draft 2020-12 subset) for documentation and third-party tooling.
+"""
+from __future__ import annotations
+
+import hashlib
+import json
+import re
+from typing import Any, Dict, List, Tuple
+
+CONTRACT_NAME = "hermes.architecture"
+CONTRACT_MAJOR = 1
+CONTRACT_MINOR = 0
+CONTRACT_VERSION = f"{CONTRACT_MAJOR}.{CONTRACT_MINOR}"
+
+REQUIRED_SECTIONS: Tuple[str, ...] = ("components", "interplay", "extraction", "ci", "inventory", "evidence_metadata")
+OPTIONAL_SECTIONS: Tuple[str, ...] = ("stores", "externals", "layers", "edges", "behavior")
+
+SEMVER_RE = re.compile(r"^(\d+)\.(\d+)\.(\d+)$")
+IDENTIFIER_RE = r"^\S.*$"
+
+# ── Schema ───────────────────────────────────────────────────────────────────
+# A JSON Schema subset: type (string or list), required, properties,
+# additionalProperties (bool), items, enum, minItems, minimum, pattern, $ref
+# into $defs. Anything not listed under `properties` is allowed (forward compat).
+
+
+def _obj(required: List[str], properties: Dict[str, Any], **extra: Any) -> Dict[str, Any]:
+ schema: Dict[str, Any] = {"type": "object", "required": required, "properties": properties}
+ schema.update(extra)
+ return schema
+
+
+def _arr(items: Any, min_items: int = 0) -> Dict[str, Any]:
+ schema: Dict[str, Any] = {"type": "array", "items": items}
+ if min_items:
+ schema["minItems"] = min_items
+ return schema
+
+
+_STR: Dict[str, Any] = {"type": "string"}
+_ID: Dict[str, Any] = {"type": "string", "pattern": IDENTIFIER_RE}
+_INT: Dict[str, Any] = {"type": "integer", "minimum": 0}
+_BOOL: Dict[str, Any] = {"type": "boolean"}
+_NULLABLE_STR: Dict[str, Any] = {"type": ["string", "null"]}
+_STR_LIST: Dict[str, Any] = _arr(_STR)
+
+SCHEMA: Dict[str, Any] = {
+ "$schema": "https://json-schema.org/draft/2020-12/schema",
+ "$id": f"https://hermes.dev/contracts/{CONTRACT_NAME}/v{CONTRACT_MAJOR}",
+ "title": f"{CONTRACT_NAME} document v{CONTRACT_VERSION}",
+ "type": "object",
+ "required": ["schema_version", "title", "description", "source_tree_sha256", *REQUIRED_SECTIONS],
+ "properties": {
+ "schema_version": {"type": "string", "pattern": SEMVER_RE.pattern},
+ "title": _STR,
+ "description": _STR,
+ "repository": _NULLABLE_STR,
+ "source_tree_sha256": {"type": "string", "pattern": r"^[0-9a-f]{64}$"},
+ "components": _arr({"$ref": "#/$defs/component"}, 1),
+ "interplay": {"$ref": "#/$defs/interplay"},
+ "extraction": {"$ref": "#/$defs/extraction"},
+ "ci": {"$ref": "#/$defs/ci"},
+ "inventory": _obj(["files", "lines", "declarations"], {"files": _INT, "lines": _INT, "declarations": _INT}),
+ "evidence_metadata": _obj(["class", "rules", "limitations"], {"class": _STR, "rules": {"type": "object"}, "limitations": _STR_LIST}),
+ "layers": _arr(_obj(["id", "label", "order"], {"id": _ID, "label": _STR, "order": {"type": "integer"}})),
+ "edges": _arr(_obj(["source", "target", "type"], {"source": _ID, "target": _ID, "type": _STR, "authority": _STR})),
+ "stores": _obj(["items"], {"count": _INT, "items": _arr({"$ref": "#/$defs/store"})}),
+ "externals": _obj(["systems"], {"systems": _arr({"$ref": "#/$defs/external"}), "groups": _arr(_obj(["id", "label"], {"id": _ID, "label": _STR})), "edges": {"type": "array"}}),
+ "behavior": {"type": "object"},
+ },
+ "$defs": {
+ "evidence": _obj(["path", "line"], {"path": _STR, "line": {"type": "integer", "minimum": 1}, "excerpt": _STR}),
+ "component": _obj(
+ ["id", "label", "description", "files", "declarations", "file_count", "line_count", "declaration_count"],
+ {
+ "id": _ID, "label": _STR, "description": _STR, "layer": _STR, "external": _BOOL,
+ "files": _STR_LIST, "declarations": _STR_LIST,
+ "file_count": _INT, "line_count": _INT, "declaration_count": _INT,
+ },
+ ),
+ "interplay": _obj(
+ ["nodes", "edges", "flows", "invariants"],
+ {
+ "nodes": _arr({"$ref": "#/$defs/node"}, 1),
+ "edges": _arr({"$ref": "#/$defs/interplay_edge"}),
+ "flows": _arr({"$ref": "#/$defs/flow"}),
+ "invariants": _arr({"$ref": "#/$defs/invariant"}, 1),
+ "pages": _arr(_obj(["id", "label"], {"id": _ID, "label": _STR, "roots": _STR_LIST, "components": _STR_LIST})),
+ "boundary_groups": _arr(_obj(["id", "label", "members"], {"id": _ID, "label": _STR, "members": _STR_LIST, "description": _STR})),
+ "clusters": _arr(_obj(["id", "node_ids"], {"id": _ID, "node_ids": _STR_LIST, "owner_type": _NULLABLE_STR})),
+ "triggers": {"type": "array"},
+ "launch": {"type": "object"},
+ "machines": {"type": "object"},
+ },
+ ),
+ "node": _obj(
+ ["id", "kind", "label"],
+ {
+ "id": _ID, "kind": _ID, "label": _STR, "sub_kind": _NULLABLE_STR, "component": _NULLABLE_STR,
+ "path": _STR, "line": {"type": "integer", "minimum": 1}, "page": _NULLABLE_STR,
+ "owner_type": _NULLABLE_STR, "cluster": _STR, "history_key": _STR,
+ "evidence": _arr({"$ref": "#/$defs/evidence"}),
+ },
+ ),
+ "interplay_edge": _obj(
+ ["source", "target", "relation", "class"],
+ {
+ "source": _ID, "target": _ID, "relation": _ID,
+ "class": {"type": "string", "enum": ["structure", "interplay", "lifecycle", "boundary", "usage"]},
+ },
+ ),
+ "flow": _obj(
+ ["id", "title", "steps"],
+ {
+ "id": _ID, "title": _STR, "summary": _STR, "page": _NULLABLE_STR, "authority": _STR,
+ "status": _STR, "interaction": _STR, "outcome": _STR, "journey": _STR,
+ "steps": _arr(_obj(["from", "to", "relation"], {"from": _ID, "to": _ID, "relation": _ID, "note": _STR}), 1),
+ "evidence": _arr({"$ref": "#/$defs/evidence"}),
+ },
+ ),
+ "invariant": _obj(
+ ["id", "kind", "status", "why"],
+ {
+ "id": _ID, "kind": _ID, "why": _STR, "checked": _INT,
+ "status": {"type": "string", "enum": ["holds", "violated", "unchecked"]},
+ },
+ ),
+ "extraction": _obj(
+ ["authority", "derivation", "files", "passes", "entities", "summary"],
+ {
+ "authority": {"type": "string", "enum": ["observed", "declared"]},
+ "derivation": _STR,
+ "families": {"type": "object"},
+ "files": _arr({"$ref": "#/$defs/extraction_file"}, 1),
+ "passes": _arr({"$ref": "#/$defs/extraction_pass"}, 1),
+ "entities": _arr({"$ref": "#/$defs/extraction_entity"}, 1),
+ "summary": _obj(
+ ["files", "touched_files", "untouched_files", "declarations", "mapped_declarations", "entities", "entities_with_origin", "passes"],
+ {
+ "files": _INT, "touched_files": _INT, "untouched_files": _INT, "declarations": _INT,
+ "mapped_declarations": _INT, "entities": _INT, "entities_with_origin": _INT, "passes": _INT,
+ "citations": _INT, "semantic_citations": _INT, "by_kind": {"type": "object"},
+ "types": {"type": "object"}, "functions": {"type": "object"},
+ },
+ ),
+ },
+ ),
+ "extraction_file": _obj(
+ ["path", "line_count", "declarations", "passes", "citations", "touched", "declaration_count", "mapped_declarations"],
+ {
+ "path": _STR, "component": _NULLABLE_STR, "line_count": _INT, "citations": _INT, "semantic_citations": _INT,
+ "touched": _BOOL, "declaration_count": _INT, "mapped_declarations": _INT, "passes": _STR_LIST,
+ "declarations": _arr(_obj(["kind", "name", "line", "passes"], {"kind": _ID, "name": _STR, "line": {"type": "integer", "minimum": 1}, "passes": _STR_LIST})),
+ },
+ ),
+ "extraction_pass": _obj(
+ ["id", "class", "description", "files", "citations"],
+ {"id": _ID, "class": {"type": "string", "enum": ["mechanical", "semantic"]}, "description": _STR, "files": _INT, "citations": _INT},
+ ),
+ "extraction_entity": _obj(
+ ["id", "kind", "label", "origins"],
+ {
+ "id": _ID, "kind": _ID, "label": _STR, "component": _NULLABLE_STR,
+ "origins": _arr(_obj(["path", "line", "rule", "family"], {"path": _STR, "line": {"type": "integer", "minimum": 1}, "rule": _ID, "family": _ID, "via": _STR}), 1),
+ },
+ ),
+ "ci": _obj(
+ ["workflows", "jobs", "edges", "merge", "ratchets", "static_checks", "summary"],
+ {
+ "workflows": _arr({"$ref": "#/$defs/ci_workflow"}, 1),
+ "jobs": _arr({"$ref": "#/$defs/ci_job"}, 1),
+ "edges": _arr(_obj(["source", "target", "kind"], {"source": _ID, "target": _ID, "kind": _ID, "label": _STR})),
+ "triggers": _arr(_obj(["id", "event", "workflows"], {"id": _ID, "event": _STR, "workflows": _STR_LIST})),
+ "merge": _obj(["id", "label", "inputs"], {"id": _ID, "label": _STR, "inputs": _arr(_ID, 1)}),
+ "ratchets": _arr({"$ref": "#/$defs/ci_ratchet"}),
+ "static_checks": _arr(_obj(["name", "command", "job"], {"name": _STR, "command": _STR, "job": _ID, "scripts": _STR_LIST, "evidence": {"$ref": "#/$defs/evidence"}})),
+ "architectural": {"type": "object"},
+ "families": {"type": "object"},
+ "limitations": _STR_LIST,
+ "summary": _obj(["workflows", "jobs", "gates"], {"workflows": _INT, "jobs": _INT, "gates": _INT, "ratchets": _INT, "static_checks": _INT}),
+ },
+ ),
+ "ci_workflow": _obj(
+ ["id", "label", "family", "jobs"],
+ {"id": _ID, "label": _STR, "name": _STR, "family": _ID, "jobs": _STR_LIST, "events": _STR_LIST, "path": _STR, "question": _STR},
+ ),
+ "ci_job": _obj(
+ ["id", "name", "workflow", "family", "role", "needs"],
+ {
+ "id": _ID, "key": _STR, "name": _STR, "workflow": _ID, "family": _ID,
+ "role": {"type": "string", "enum": ["gate", "post-merge", "manual", "disabled", "local"]},
+ "needs": _STR_LIST, "runs_on": _STR, "condition": _NULLABLE_STR,
+ "steps": {"type": "array"}, "step_count": _INT, "scripts": _STR_LIST,
+ "artifacts_in": _STR_LIST, "artifacts_out": _STR_LIST, "pins": {"type": "array"},
+ "evidence": {"$ref": "#/$defs/evidence"},
+ },
+ ),
+ "ci_ratchet": _obj(
+ ["id", "title", "job", "measures", "floor"],
+ {"id": _ID, "title": _STR, "job": _ID, "measures": _STR, "floor": _STR, "patch": _NULLABLE_STR, "source": {"type": "object"}, "source_path": _STR, "current": {"type": "object"}},
+ ),
+ "store": _obj(["id", "label", "kind"], {"id": _ID, "label": _STR, "kind": _STR, "component": _NULLABLE_STR, "persistence": {"type": "array"}, "evidence": {"$ref": "#/$defs/evidence"}}),
+ "external": _obj(["id", "label", "category"], {"id": _ID, "label": _STR, "category": _STR, "description": _STR, "component": _NULLABLE_STR, "hit_count": _INT, "file_count": _INT}),
+ },
+}
+
+
+# ── Structural validation ────────────────────────────────────────────────────
+
+_TYPE_CHECKS = {
+ "object": lambda v: isinstance(v, dict),
+ "array": lambda v: isinstance(v, list),
+ "string": lambda v: isinstance(v, str),
+ "integer": lambda v: isinstance(v, int) and not isinstance(v, bool),
+ "number": lambda v: isinstance(v, (int, float)) and not isinstance(v, bool),
+ "boolean": lambda v: isinstance(v, bool),
+ "null": lambda v: v is None,
+}
+
+
+def _resolve(schema: Dict[str, Any]) -> Dict[str, Any]:
+ ref = schema.get("$ref")
+ if not ref:
+ return schema
+ assert ref.startswith("#/$defs/"), ref
+ return SCHEMA["$defs"][ref[len("#/$defs/"):]]
+
+
+def _check(value: Any, schema: Dict[str, Any], path: str, problems: List[str]) -> None:
+ schema = _resolve(schema)
+ expected = schema.get("type")
+ if expected is not None:
+ types = expected if isinstance(expected, list) else [expected]
+ if not any(_TYPE_CHECKS[t](value) for t in types):
+ problems.append(f"{path}: expected {' or '.join(types)}, got {type(value).__name__}")
+ return
+ if "enum" in schema and value not in schema["enum"]:
+ problems.append(f"{path}: {value!r} is not one of {schema['enum']}")
+ return
+ if isinstance(value, str) and "pattern" in schema and not re.match(schema["pattern"], value):
+ problems.append(f"{path}: {value!r} does not match {schema['pattern']}")
+ if isinstance(value, (int, float)) and not isinstance(value, bool) and "minimum" in schema and value < schema["minimum"]:
+ problems.append(f"{path}: {value} is below the minimum {schema['minimum']}")
+ if isinstance(value, dict):
+ for key in schema.get("required", []):
+ if key not in value:
+ problems.append(f"{path}: missing required field {key!r}")
+ properties = schema.get("properties", {})
+ for key, child in value.items():
+ if key in properties:
+ _check(child, properties[key], f"{path}.{key}", problems)
+ elif schema.get("additionalProperties") is False:
+ problems.append(f"{path}: unexpected field {key!r}")
+ if isinstance(value, list):
+ if len(value) < schema.get("minItems", 0):
+ problems.append(f"{path}: needs at least {schema['minItems']} item(s), has {len(value)}")
+ items = schema.get("items")
+ if items is not None:
+ for index, child in enumerate(value):
+ _check(child, items, f"{path}[{index}]", problems)
+
+
+def validate_structure(document: Any) -> List[str]:
+ """Shape problems only: types, required fields, enums, patterns."""
+ problems: List[str] = []
+ _check(document, SCHEMA, "document", problems)
+ return problems
+
+
+# ── Version ──────────────────────────────────────────────────────────────────
+
+
+def parse_version(document: Any) -> Tuple[int, int, int]:
+ """The document's semver as integers; (0, 0, 0) when absent or malformed."""
+ if not isinstance(document, dict):
+ return (0, 0, 0)
+ match = SEMVER_RE.match(str(document.get("schema_version") or ""))
+ return tuple(int(part) for part in match.groups()) if match else (0, 0, 0) # type: ignore[return-value]
+
+
+def validate_version(document: Any) -> List[str]:
+ major, minor, _ = parse_version(document)
+ if major == 0 and minor == 0:
+ return [f"document.schema_version: missing or not semver (contract {CONTRACT_NAME} v{CONTRACT_VERSION})"]
+ if major != CONTRACT_MAJOR:
+ return [f"document.schema_version: major {major} is not supported (this consumer speaks {CONTRACT_NAME} v{CONTRACT_MAJOR}.x)"]
+ return []
+
+
+# ── Cross-reference validation ───────────────────────────────────────────────
+
+
+def _ids(items: Any, key: str = "id") -> List[str]:
+ return [str(item[key]) for item in items or [] if isinstance(item, dict) and key in item]
+
+
+def _duplicates(values: List[str]) -> List[str]:
+ seen: set = set()
+ dupes: List[str] = []
+ for value in values:
+ if value in seen and value not in dupes:
+ dupes.append(value)
+ seen.add(value)
+ return dupes
+
+
+def validate_references(document: Dict[str, Any]) -> List[str]:
+ """Every reference resolves and every construction has provenance and gates.
+ Assumes the structure validated; tolerates missing pieces without crashing."""
+ problems: List[str] = []
+ components = document.get("components") or []
+ component_ids = set(_ids(components))
+ for dupe in _duplicates(_ids(components)):
+ problems.append(f"components: duplicate id {dupe!r}")
+
+ interplay = document.get("interplay") if isinstance(document.get("interplay"), dict) else {}
+ nodes = interplay.get("nodes") or []
+ node_ids = set(_ids(nodes))
+ for dupe in _duplicates(_ids(nodes)):
+ problems.append(f"interplay.nodes: duplicate id {dupe!r}")
+ for node in nodes:
+ if isinstance(node, dict) and node.get("component") not in (None, "") and node["component"] not in component_ids:
+ problems.append(f"interplay.nodes[{node.get('id')}]: component {node['component']!r} is not declared")
+ for index, edge in enumerate(interplay.get("edges") or []):
+ if not isinstance(edge, dict):
+ continue
+ for end in ("source", "target"):
+ if edge.get(end) not in node_ids:
+ problems.append(f"interplay.edges[{index}]: {end} {edge.get(end)!r} is not a node")
+ # Flow steps walk the drawn map, which also has page pseudo-nodes (page:<id>)
+ # and the lifecycle wiring the renderer derives from operations and triggers;
+ # the compiler's own flows-traceable invariant checks each hop against that
+ # fuller set. The contract checks that every step ends on something that exists.
+ # Steps name nodes by their stable history_key (the identity that survives
+ # re-extraction), falling back to the id, plus page pseudo-nodes (page:<id>).
+ step_targets = node_ids | {str(n.get("history_key")) for n in nodes if isinstance(n, dict) and n.get("history_key")}
+ step_targets |= {f"page:{p['id']}" for p in interplay.get("pages") or [] if isinstance(p, dict) and "id" in p}
+ for flow in interplay.get("flows") or []:
+ if not isinstance(flow, dict):
+ continue
+ for index, step in enumerate(flow.get("steps") or []):
+ if not isinstance(step, dict):
+ continue
+ for end in ("from", "to"):
+ if step.get(end) not in step_targets:
+ problems.append(f"interplay.flows[{flow.get('id')}].steps[{index}]: {end} {step.get(end)!r} is not on the map")
+ for dupe in _duplicates(_ids(interplay.get("invariants") or [])):
+ problems.append(f"interplay.invariants: duplicate id {dupe!r}")
+
+ extraction = document.get("extraction") if isinstance(document.get("extraction"), dict) else {}
+ files = extraction.get("files") or []
+ file_paths = set(str(f.get("path")) for f in files if isinstance(f, dict))
+ for dupe in _duplicates([str(f.get("path")) for f in files if isinstance(f, dict)]):
+ problems.append(f"extraction.files: duplicate path {dupe!r}")
+ passes = extraction.get("passes") or []
+ pass_ids = set(_ids(passes))
+ if not any(isinstance(p, dict) and p.get("class") == "mechanical" for p in passes):
+ problems.append("extraction.passes: no mechanical pass — an extraction map must come from the extractor, not only from people")
+ for record in files:
+ if not isinstance(record, dict):
+ continue
+ if record.get("component") not in (None, "") and record["component"] not in component_ids:
+ problems.append(f"extraction.files[{record.get('path')}]: component {record['component']!r} is not declared")
+ for pass_id in record.get("passes") or []:
+ if pass_id not in pass_ids:
+ problems.append(f"extraction.files[{record.get('path')}]: pass {pass_id!r} is not declared")
+ if bool(record.get("touched")) != (int(record.get("citations") or 0) > 0):
+ problems.append(f"extraction.files[{record.get('path')}]: touched must equal citations > 0")
+ entities = extraction.get("entities") or []
+ entity_ids = set(_ids(entities))
+ for dupe in _duplicates(_ids(entities)):
+ problems.append(f"extraction.entities: duplicate id {dupe!r}")
+ for missing in sorted(node_ids - entity_ids):
+ problems.append(f"extraction.entities: construction {missing!r} has no provenance")
+ for orphan in sorted(entity_ids - node_ids):
+ problems.append(f"extraction.entities: {orphan!r} is not a construction on the map")
+ for entity in entities:
+ if not isinstance(entity, dict):
+ continue
+ for index, origin in enumerate(entity.get("origins") or []):
+ if not isinstance(origin, dict):
+ continue
+ if origin.get("path") not in file_paths:
+ problems.append(f"extraction.entities[{entity.get('id')}].origins[{index}]: {origin.get('path')!r} is not an analysed file")
+ rule = str(origin.get("rule") or "")
+ if rule not in pass_ids and not rule.startswith("map."):
+ problems.append(f"extraction.entities[{entity.get('id')}].origins[{index}]: rule {rule!r} is not a declared pass")
+
+ ci = document.get("ci") if isinstance(document.get("ci"), dict) else {}
+ jobs = ci.get("jobs") or []
+ job_ids = set(_ids(jobs))
+ for dupe in _duplicates(_ids(jobs)):
+ problems.append(f"ci.jobs: duplicate id {dupe!r}")
+ workflow_ids = set(_ids(ci.get("workflows") or []))
+ for job in jobs:
+ if not isinstance(job, dict):
+ continue
+ if job.get("workflow") not in workflow_ids:
+ problems.append(f"ci.jobs[{job.get('id')}]: workflow {job.get('workflow')!r} is not declared")
+ for need in job.get("needs") or []:
+ if need not in job_ids:
+ problems.append(f"ci.jobs[{job.get('id')}]: needs {need!r} which is not a job")
+ for workflow in ci.get("workflows") or []:
+ if isinstance(workflow, dict):
+ for job_id in workflow.get("jobs") or []:
+ if job_id not in job_ids:
+ problems.append(f"ci.workflows[{workflow.get('id')}]: lists job {job_id!r} which is not declared")
+ trigger_ids = set(_ids(ci.get("triggers") or []))
+ merge = ci.get("merge") if isinstance(ci.get("merge"), dict) else {}
+ wire_targets = job_ids | trigger_ids | ({str(merge.get("id"))} if merge.get("id") else set())
+ for index, edge in enumerate(ci.get("edges") or []):
+ if not isinstance(edge, dict):
+ continue
+ for end in ("source", "target"):
+ if edge.get(end) not in wire_targets:
+ problems.append(f"ci.edges[{index}]: {end} {edge.get(end)!r} is not a job, trigger or the merge gate")
+ for job_id in merge.get("inputs") or []:
+ if job_id not in job_ids:
+ problems.append(f"ci.merge: input {job_id!r} is not a job")
+ for ratchet in ci.get("ratchets") or []:
+ if isinstance(ratchet, dict) and ratchet.get("job") not in job_ids:
+ problems.append(f"ci.ratchets[{ratchet.get('id')}]: job {ratchet.get('job')!r} is not declared")
+ for check in ci.get("static_checks") or []:
+ if isinstance(check, dict) and check.get("job") not in job_ids:
+ problems.append(f"ci.static_checks[{check.get('name')}]: job {check.get('job')!r} is not declared")
+ return problems
+
+
+def validate_document(document: Any) -> List[str]:
+ """Every problem with a document, or an empty list when it conforms.
+ Version first (so an unsupported major is one clear message), then shape,
+ then references (only when the shape holds, so messages stay meaningful)."""
+ problems = validate_version(document)
+ if problems:
+ return problems
+ problems = validate_structure(document)
+ if problems:
+ return problems
+ return validate_references(document)
+
+
+def conforms(document: Any) -> bool:
+ return not validate_document(document)
+
+
+# ── Export and pinning ───────────────────────────────────────────────────────
+
+
+def schema_json() -> str:
+ """The schema as JSON Schema text, stable across runs, for docs and tooling."""
+ return json.dumps(SCHEMA, indent=2, sort_keys=True) + "\n"
+
+
+def schema_digest() -> str:
+ """sha256 of the exported schema: the value each repository pins."""
+ return hashlib.sha256(schema_json().encode("utf-8")).hexdigest()
+
+
+def describe_contract() -> Dict[str, Any]:
+ """What a gateway advertises and what a consumer checks against."""
+ return {
+ "name": CONTRACT_NAME,
+ "version": CONTRACT_VERSION,
+ "major": CONTRACT_MAJOR,
+ "minor": CONTRACT_MINOR,
+ "required_sections": list(REQUIRED_SECTIONS),
+ "optional_sections": list(OPTIONAL_SECTIONS),
+ "schema_digest": schema_digest(),
+ }
+
+
+if __name__ == "__main__": # pragma: no cover - CLI convenience
+ import sys
+
+ if len(sys.argv) > 1 and sys.argv[1] == "--schema":
+ sys.stdout.write(schema_json())
+ raise SystemExit(0)
+ if len(sys.argv) > 1 and sys.argv[1] == "--digest":
+ print(schema_digest())
+ raise SystemExit(0)
+ documents = sys.argv[1:] or ["architecture/model/model.json"]
+ status = 0
+ for path in documents:
+ with open(path, "rb") as handle:
+ loaded = json.loads(handle.read().decode("utf-8"))
+ issues = validate_document(loaded)
+ if issues:
+ status = 1
+ print(f"{path}: {len(issues)} problem(s)")
+ for issue in issues:
+ print(f" - {issue}")
+ else:
+ print(f"{path}: conforms to {CONTRACT_NAME} v{CONTRACT_VERSION}")
+ raise SystemExit(status)
diff --git hermes-agent/tui_gateway/architecture_store.py harness/tui_gateway/architecture_store.py
new file mode 100644
index 0000000000000000000000000000000000000000..367d7cff664d8e7d4ce2ad4962b68c2ad982cb3a
--- /dev/null
+++ harness/tui_gateway/architecture_store.py
@@ -0,0 +1,971 @@
+"""Architecture models per service: manifests, snapshots, checks.
+
+A service that conforms to the architecture standard ships a compiler that emits
+an *architecture model* (``architecture/model/model.json`` — components, the
+system map, invariants with status, stores, externals, the CI plane) and a
+``--check`` that fails when the committed model drifts from the tree. Harness
+learns about such a service from a **manifest**: one JSON file per service under
+``~/.hermes/services/architecture/<id>.json``. The manifest is the durable,
+operator-owned object; everything else here is derived from it.
+
+Two kinds of service share one manifest shape and one read path:
+
+* **local** — a checkout Harness can reach (``root``). The model is read from the
+ tree, the revision is the checkout's ``git`` head (or a content digest when
+ there is no repository), and ``check`` — the compiler's own ``--check`` — can be
+ run on demand. This is the never-pushed case; nothing leaves the machine.
+* **github** — a repository (``repository`` + ``ref``). The model is fetched from
+ the repository at that ref; checks come from the repository's own CI, so
+ ``architecture.check`` reports them as unavailable here.
+
+Manifest shape (``name`` and ``description`` required; ``root`` or ``repository``
+required; the rest optional)::
+
+ {
+ "id": "portal", # defaults to the file stem
+ "name": "Portal", # display name
+ "description": "Native macOS/iOS client …", # markdown detail card
+ "root": "/Users/me/Desktop/portal", # local checkout
+ "repository": "owner/name", "ref": "main", # or a GitHub repository
+ "model": "architecture/model/model.json", # path inside root/repo
+ "check": ["python3", "scripts/build_architecture.py", "--check"],
+ "source_files": ["scripts/build_architecture.py"],
+ "inputs": [], "outputs": [], "side_effects": [], "relationships": [],
+ "deployments": [ … ] # where the code runs off this machine; see tui_gateway/deployments.py
+ }
+Every model read is validated against the ``hermes.architecture`` contract
+(``architecture_contract.py``, vendored byte-for-byte into every consumer): a
+document that does not conform is refused with error 4033 and never
+snapshotted, so a stored revision is always a conforming one.
+
+Every revision read is stored as a **snapshot** under
+``~/.hermes/architecture/<id>/<revision>.json`` with an index, so Portal can walk
+a service's models over time; the first snapshot (genesis) is never pruned.
+Check runs land in ``checks.json`` beside them.
+"""
+from __future__ import annotations
+
+import hashlib
+import json
+import logging
+import os
+import re
+import subprocess
+import tempfile
+import threading
+import time
+import urllib.error
+import urllib.request
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any, Callable, Dict, List, Optional
+
+from hermes_constants import get_hermes_home
+
+from tui_gateway import architecture_contract as contract
+
+logger = logging.getLogger(__name__)
+
+SERVICE_ID_RE = re.compile(r"^[a-z0-9][a-z0-9._-]{0,63}$")
+REPOSITORY_RE = re.compile(r"^[A-Za-z0-9_.-]+/[A-Za-z0-9_.-]+$")
+REF_RE = re.compile(r"^[A-Za-z0-9][A-Za-z0-9._/-]{0,127}$")
+DEFAULT_MODEL_PATH = "architecture/model/model.json"
+MAX_MODEL_BYTES = 16 * 1024 * 1024
+MAX_SNAPSHOTS = 30
+MAX_CHECKS = 20
+MAX_CHECK_OUTPUT = 4000
+CHECK_TIMEOUT_S = 300.0
+FETCH_TIMEOUT_S = 20.0
+# The prefix every architecture service id carries on the dataflow graph, so it
+# can never collide with a resource ref, a cron id, or a proc_/docker:/nomad:/
+# launchd: service id.
+ID_PREFIX = "arch:"
+# A manifest may bind to a service another provider already puts on the graph
+# (``"runtime": {"provider": "launchd", "id": "ai.hermes.gateway"}``); the
+# architecture then annotates that runtime node instead of adding an ``arch:``
+# node beside it. The canonical graph identity per provider mirrors what the
+# provider's own collector emits, so a binding is exact, never a name match.
+RUNTIME_PROVIDERS = ("launchd", "docker", "nomad", "process")
+RUNTIME_ID_RE = re.compile(r"^[A-Za-z0-9][A-Za-z0-9._@:/-]{0,127}$")
+
+_lock = threading.Lock()
+
+
+class ArchitectureError(Exception):
+ """A user-facing failure with a JSON-RPC error code."""
+
+ def __init__(self, code: int, message: str) -> None:
+ super().__init__(message)
+ self.code = code
+ self.message = message
+
+
+# ── Paths ────────────────────────────────────────────────────────────────────
+
+
+def manifests_dir(home: Optional[str] = None) -> Path:
+ base = Path(home) if home else Path(get_hermes_home())
+ return base / "services" / "architecture"
+
+
+def snapshots_root(home: Optional[str] = None) -> Path:
+ base = Path(home) if home else Path(get_hermes_home())
+ return base / "architecture"
+
+
+def _safe_dir_name(service_id: str) -> str:
+ return re.sub(r"[^A-Za-z0-9_.-]", "_", service_id)
+
+
+def service_dir(service_id: str, home: Optional[str] = None) -> Path:
+ return snapshots_root(home) / _safe_dir_name(service_id)
+
+
+def _now_iso() -> str:
+ return datetime.now(timezone.utc).isoformat()
+
+
+def _read_json(path: Path, default):
+ if not path.exists():
+ return default
+ try:
+ with open(path, encoding="utf-8") as f:
+ data = json.load(f)
+ return data if isinstance(data, type(default)) else default
+ except (json.JSONDecodeError, OSError):
+ return default
+
+
+def _write_json(path: Path, payload) -> None:
+ path.parent.mkdir(parents=True, exist_ok=True)
+ fd, tmp = tempfile.mkstemp(dir=str(path.parent), suffix=".json")
+ try:
+ with os.fdopen(fd, "w", encoding="utf-8") as f:
+ json.dump(payload, f, indent=2, ensure_ascii=False)
+ os.replace(tmp, str(path))
+ except Exception:
+ try:
+ os.unlink(tmp)
+ except OSError:
+ pass
+ raise
+
+
+# ── Manifests ────────────────────────────────────────────────────────────────
+
+
+def _string_list(value: Any, field: str) -> List[str]:
+ if value is None:
+ return []
+ if isinstance(value, str):
+ value = [value]
+ if not isinstance(value, list) or not all(isinstance(item, str) for item in value):
+ raise ValueError(f"{field} must be a list of strings")
+ return [item.strip() for item in value if item.strip()]
+
+
+def runtime_graph_id(provider: str, runtime_id: str) -> str:
+ """The graph node id the named provider gives this runtime service."""
+ if provider == "launchd":
+ return f"launchd:{runtime_id}"
+ if provider == "docker":
+ return f"docker:{runtime_id[:12]}"
+ if provider == "nomad":
+ return f"nomad:{runtime_id}"
+ if provider == "process":
+ return runtime_id if runtime_id.startswith("proc_") else f"proc_{runtime_id}"
+ raise ValueError(f"unsupported runtime provider {provider!r}")
+
+
+def normalize_runtime_binding(value: Any) -> Dict[str, str]:
+ """Validate ``runtime: {provider, id}``. Raises ValueError with a reason."""
+ if not isinstance(value, dict):
+ raise ValueError("runtime must be an object with provider and id")
+ provider = value.get("provider")
+ runtime_id = value.get("id")
+ if not isinstance(provider, str) or provider not in RUNTIME_PROVIDERS:
+ raise ValueError(f"runtime.provider must be one of {', '.join(RUNTIME_PROVIDERS)}")
+ if not isinstance(runtime_id, str) or not runtime_id.strip():
+ raise ValueError("runtime.id must be a non-empty string")
+ runtime_id = runtime_id.strip()
+ if not RUNTIME_ID_RE.match(runtime_id) or runtime_id.startswith(ID_PREFIX):
+ raise ValueError(f"runtime.id {runtime_id!r} is not a valid {provider} identity")
+ for prefix in ("launchd:", "docker:", "nomad:"):
+ if runtime_id.startswith(prefix):
+ raise ValueError(f"runtime.id must be the provider's own id, without the {prefix!r} prefix")
+ return {"provider": provider, "id": runtime_id, "graph_id": runtime_graph_id(provider, runtime_id)}
+
+
+def normalize_manifest(doc: Any, stem: str, launchd_dirs: Optional[List[str]] = None) -> Dict[str, Any]:
+ """Validate one manifest document. Raises ValueError with a reason.
+ ``launchd_dirs`` overrides where launchd plists are looked up (tests)."""
+ if not isinstance(doc, dict):
+ raise ValueError("manifest must be a JSON object")
+ service_id = doc.get("id", stem)
+ if not isinstance(service_id, str) or not SERVICE_ID_RE.match(service_id):
+ raise ValueError("id must match ^[a-z0-9][a-z0-9._-]{0,63}$")
+ if service_id != stem:
+ raise ValueError(f"id {service_id!r} must match the file name {stem!r}")
+ name = doc.get("name")
+ description = doc.get("description")
+ if not isinstance(name, str) or not name.strip():
+ raise ValueError("name is required")
+ if not isinstance(description, str) or not description.strip():
+ raise ValueError("description is required (markdown shown on the service node)")
+ root = doc.get("root")
+ repository = doc.get("repository")
+ if root is None and repository is None:
+ raise ValueError("a manifest needs a local root or a GitHub repository")
+ if root is not None:
+ if not isinstance(root, str) or not root.strip():
+ raise ValueError("root must be a non-empty path")
+ root = str(Path(root).expanduser())
+ if not os.path.isabs(root):
+ raise ValueError("root must be an absolute path")
+ if repository is not None:
+ if not isinstance(repository, str) or not REPOSITORY_RE.match(repository):
+ raise ValueError("repository must be owner/name")
+ ref = doc.get("ref", "main")
+ if not isinstance(ref, str) or not REF_RE.match(ref):
+ raise ValueError("ref must be a branch, tag or commit")
+ model = doc.get("model", DEFAULT_MODEL_PATH)
+ if not isinstance(model, str) or not model.strip() or model.startswith("/") or ".." in model.split("/"):
+ raise ValueError("model must be a relative path inside the service")
+ check = doc.get("check")
+ if check is not None:
+ if not isinstance(check, list) or not check or not all(isinstance(part, str) and part for part in check):
+ raise ValueError("check must be a non-empty argv list")
+ manifest: Dict[str, Any] = {
+ "id": service_id,
+ "name": name.strip(),
+ "description": description.strip(),
+ "root": root,
+ "repository": repository,
+ "ref": ref,
+ "model": model.strip(),
+ "check": list(check) if check else None,
+ "source_files": _string_list(doc.get("source_files"), "source_files"),
+ "inputs": _string_list(doc.get("inputs"), "inputs"),
+ "outputs": _string_list(doc.get("outputs"), "outputs"),
+ "side_effects": _string_list(doc.get("side_effects"), "side_effects"),
+ }
+ if doc.get("relationships") is not None:
+ manifest["relationships"] = doc["relationships"]
+ if doc.get("runtime") is not None:
+ manifest["runtime"] = normalize_runtime_binding(doc["runtime"])
+ # Deployments: environments the codebase runs in that no local provider can
+ # see, each with its own health probe, revision probe and command log sinks.
+ from tui_gateway import deployments as _deployments
+ manifest["deployments"] = _deployments.normalize_deployments(doc.get("deployments"), service_id)
+ # Log capture: declared sinks (validated here; enforced for local services
+ # in conformance_for). A GitHub-only service has no runtime here, so its
+ # sinks are dropped with a warning rather than pretending to be readable.
+ from tui_gateway import service_logs
+
+ sinks = service_logs.normalize_log_sinks(doc.get("logs"), manifest.get("runtime"), launchd_dirs)
+ if sinks and root is None:
+ logger.warning("architecture manifest %s declares logs but has no local root; sinks ignored", service_id)
+ sinks = []
+ manifest["logs"] = sinks
+ return manifest
+
+
+def list_manifests(home: Optional[str] = None) -> List[Dict[str, Any]]:
+ """Every valid manifest, sorted by id. Malformed files are logged and skipped."""
+ directory = manifests_dir(home)
+ if not directory.is_dir():
+ return []
+ manifests: List[Dict[str, Any]] = []
+ for path in sorted(directory.glob("*.json")):
+ try:
+ with open(path, encoding="utf-8") as f:
+ doc = json.load(f)
+ manifests.append(normalize_manifest(doc, path.stem))
+ except (OSError, json.JSONDecodeError, ValueError) as exc:
+ logger.warning("architecture manifest %s invalid: %s", path.name, exc)
+ return manifests
+
+
+def load_manifest(service_id: str, home: Optional[str] = None) -> Optional[Dict[str, Any]]:
+ """The manifest for ``service_id`` (with or without the ``arch:`` prefix)."""
+ bare = service_id[len(ID_PREFIX):] if service_id.startswith(ID_PREFIX) else service_id
+ if not SERVICE_ID_RE.match(bare):
+ return None
+ path = manifests_dir(home) / f"{bare}.json"
+ if not path.is_file():
+ return None
+ try:
+ with open(path, encoding="utf-8") as f:
+ return normalize_manifest(json.load(f), bare)
+ except (OSError, json.JSONDecodeError, ValueError) as exc:
+ logger.warning("architecture manifest %s invalid: %s", path.name, exc)
+ return None
+
+
+def service_param(params: Any) -> Optional[str]:
+ """The ``service`` argument of an RPC, stripped, or None when missing/blank."""
+ service_id = (params or {}).get("service") if isinstance(params, dict) else None
+ if not isinstance(service_id, str) or not service_id.strip():
+ return None
+ return service_id.strip()
+
+
+def graph_id(manifest: Dict[str, Any]) -> str:
+ return f"{ID_PREFIX}{manifest['id']}"
+
+
+def source_of(manifest: Dict[str, Any]) -> str:
+ return "local" if manifest.get("root") else "github"
+
+
+# ── Reading the model ────────────────────────────────────────────────────────
+
+
+def _model_path(manifest: Dict[str, Any]) -> Path:
+ root = Path(manifest["root"]).resolve()
+ candidate = (root / manifest["model"]).resolve()
+ try:
+ candidate.relative_to(root)
+ except ValueError as exc:
+ raise ArchitectureError(4032, f"model path escapes the service root: {manifest['model']}") from exc
+ return candidate
+
+
+def local_revision(manifest: Dict[str, Any], git_runner: Optional[Callable[[str], str]] = None) -> str:
+ """The checkout's git head, or a content digest of the model when there is no repository."""
+ root = manifest.get("root")
+ if not root:
+ return ""
+ runner = git_runner or _git_head
+ head = runner(root)
+ if head:
+ return head
+ try:
+ path = _model_path(manifest)
+ return "sha256:" + hashlib.sha256(path.read_bytes()).hexdigest()[:16]
+ except (ArchitectureError, OSError):
+ return ""
+
+
+def _git_head(root: str) -> str:
+ try:
+ from tui_gateway.git_probe import run_git
+
+ return run_git(root, "rev-parse", "HEAD")
+ except Exception: # pragma: no cover - probe is fail-open by contract
+ return ""
+
+
+def _parse_model(raw: bytes, where: str) -> Dict[str, Any]:
+ if len(raw) > MAX_MODEL_BYTES:
+ raise ArchitectureError(4032, f"model at {where} exceeds {MAX_MODEL_BYTES} bytes")
+ try:
+ model = json.loads(raw.decode("utf-8"))
+ except (UnicodeDecodeError, json.JSONDecodeError) as exc:
+ raise ArchitectureError(4032, f"model at {where} is not valid JSON: {exc}") from exc
+ if not isinstance(model, dict) or "schema_version" not in model:
+ raise ArchitectureError(4032, f"model at {where} is not an architecture model (no schema_version)")
+ problems = contract.validate_document(model)
+ if problems:
+ raise ArchitectureError(4033, nonconforming_message(where, problems))
+ return model
+
+
+def nonconforming_message(where: str, problems: List[str], shown: int = 5) -> str:
+ """One line a client can show verbatim: which contract, where, the first
+ problems, and how many more the compiler will list."""
+ head = "; ".join(problems[:shown])
+ more = f" (+{len(problems) - shown} more)" if len(problems) > shown else ""
+ return f"model at {where} does not conform to {contract.CONTRACT_NAME} v{contract.CONTRACT_VERSION}: {head}{more}"
+
+
+def contract_ref() -> Dict[str, Any]:
+ """The contract this gateway validates against, for envelopes and annotations."""
+ return {"name": contract.CONTRACT_NAME, "version": contract.CONTRACT_VERSION}
+
+
+def read_local_model(manifest: Dict[str, Any]) -> Dict[str, Any]:
+ path = _model_path(manifest)
+ if not path.is_file():
+ raise ArchitectureError(4032, f"model not found at {path}; run the service's compiler first")
+ return _parse_model(path.read_bytes(), str(path))
+
+
+def _github_raw_url(manifest: Dict[str, Any]) -> str:
+ return f"https://raw.githubusercontent.com/{manifest['repository']}/{manifest['ref']}/{manifest['model']}"
+
+
+def read_github_model(manifest: Dict[str, Any], opener: Optional[Callable[[str, Dict[str, str]], bytes]] = None) -> Dict[str, Any]:
+ url = _github_raw_url(manifest)
+ headers: Dict[str, str] = {"User-Agent": "harness-architecture"}
+ token = os.environ.get("GITHUB_TOKEN") or os.environ.get("GH_TOKEN")
+ if token:
+ headers["Authorization"] = f"Bearer {token}"
+ fetch = opener or _http_get
+ try:
+ raw = fetch(url, headers)
+ except (urllib.error.URLError, OSError, TimeoutError) as exc:
+ raise ArchitectureError(4032, f"could not fetch {url}: {exc}") from exc
+ return _parse_model(raw, url)
+
+
+def _http_get(url: str, headers: Dict[str, str]) -> bytes:
+ request = urllib.request.Request(url, headers=headers)
+ with urllib.request.urlopen(request, timeout=FETCH_TIMEOUT_S) as response: # noqa: S310 - https to GitHub only
+ return response.read(MAX_MODEL_BYTES + 1)
+
+
+def read_model(manifest: Dict[str, Any], **kwargs: Any) -> Dict[str, Any]:
+ """The service's current model with its revision and where it came from."""
+ if manifest.get("root"):
+ model = read_local_model(manifest)
+ revision = local_revision(manifest, kwargs.get("git_runner")) or "working-tree"
+ return {"model": model, "revision": revision, "source": "local"}
+ model = read_github_model(manifest, kwargs.get("opener"))
+ revision = str(model.get("source_revision") or manifest["ref"])
+ return {"model": model, "revision": revision, "source": "github"}
+
+
+# ── Summaries ────────────────────────────────────────────────────────────────
+
+
+def summarize_model(model: Dict[str, Any]) -> Dict[str, Any]:
+ """The counts Portal shows on a service node without loading the whole model."""
+ interplay = model.get("interplay") if isinstance(model.get("interplay"), dict) else {}
+ invariants = interplay.get("invariants") if isinstance(interplay.get("invariants"), list) else []
+ ci = model.get("ci") if isinstance(model.get("ci"), dict) else {}
+ ci_summary = ci.get("summary") if isinstance(ci.get("summary"), dict) else {}
+ inventory = model.get("inventory") if isinstance(model.get("inventory"), dict) else {}
+ violated = sorted(str(item.get("id")) for item in invariants if isinstance(item, dict) and item.get("status") != "holds")
+ return {
+ "schema_version": str(model.get("schema_version") or ""),
+ "title": str(model.get("title") or ""),
+ "source_tree_sha256": str(model.get("source_tree_sha256") or ""),
+ "components": len(model.get("components") or []),
+ "files": int(inventory.get("swift_files") or inventory.get("files") or 0),
+ "lines": int(inventory.get("swift_lines") or inventory.get("lines") or 0),
+ "nodes": len(interplay.get("nodes") or []),
+ "edges": len(interplay.get("edges") or []),
+ "flows": len(interplay.get("flows") or []),
+ "invariants": {"total": len(invariants), "holds": len(invariants) - len(violated), "violated": violated},
+ "stores": len((model.get("stores") or {}).get("items") or []) if isinstance(model.get("stores"), dict) else 0,
+ "externals": len((model.get("externals") or {}).get("systems") or []) if isinstance(model.get("externals"), dict) else 0,
+ "gates": int(ci_summary.get("gates") or 0),
+ "ratchets": int(ci_summary.get("ratchets") or 0),
+ "workflows": int(ci_summary.get("workflows") or 0),
+ }
+
+
+# ── Snapshots ────────────────────────────────────────────────────────────────
+
+
+def _index_file(service_id: str, home: Optional[str] = None) -> Path:
+ return service_dir(service_id, home) / "index.json"
+
+
+def _snapshot_file(service_id: str, revision: str, home: Optional[str] = None) -> Path:
+ return service_dir(service_id, home) / f"{_safe_dir_name(revision)}.json"
+
+
+def _checks_file(service_id: str, home: Optional[str] = None) -> Path:
+ return service_dir(service_id, home) / "checks.json"
+
+
+def store_snapshot(service_id: str, revision: str, model: Dict[str, Any], source: str,
+ home: Optional[str] = None) -> Dict[str, Any]:
+ """Record one revision's model. Idempotent per revision; prunes the oldest
+ non-genesis snapshots past ``MAX_SNAPSHOTS``. Returns the index entry."""
+ with _lock:
+ index = _read_json(_index_file(service_id, home), {})
+ revisions: List[Dict[str, Any]] = [r for r in index.get("revisions", []) if isinstance(r, dict)]
+ existing = next((r for r in revisions if r.get("revision") == revision), None)
+ if existing is None:
+ entry = {
+ "revision": revision,
+ "source": source,
+ "stored_at": _now_iso(),
+ "summary": summarize_model(model),
+ # Only a validated document reaches here (read_model validates
+ # before describe() stores), so the entry records which contract.
+ "contract": contract_ref(),
+ }
+ _write_json(_snapshot_file(service_id, revision, home), model)
+ revisions.append(entry)
+ while len(revisions) > MAX_SNAPSHOTS:
+ # Genesis (the first snapshot) is kept; the oldest after it goes.
+ victim = revisions.pop(1)
+ try:
+ _snapshot_file(service_id, str(victim.get("revision")), home).unlink()
+ except OSError:
+ pass
+ else:
+ entry = existing
+ index = {"service": service_id, "latest": revision, "revisions": revisions}
+ _write_json(_index_file(service_id, home), index)
+ return entry
+
+
+def list_snapshots(service_id: str, home: Optional[str] = None) -> Dict[str, Any]:
+ index = _read_json(_index_file(service_id, home), {})
+ revisions = [r for r in index.get("revisions", []) if isinstance(r, dict)]
+ return {"service": service_id, "latest": index.get("latest"), "revisions": revisions}
+
+
+def load_snapshot(service_id: str, revision: str, home: Optional[str] = None) -> Optional[Dict[str, Any]]:
+ path = _snapshot_file(service_id, revision, home)
+ model = _read_json(path, {})
+ return model or None
+
+
+# ── Checks ───────────────────────────────────────────────────────────────────
+
+
+def record_check(service_id: str, result: Dict[str, Any], home: Optional[str] = None) -> None:
+ with _lock:
+ checks = _read_json(_checks_file(service_id, home), {})
+ runs: List[Dict[str, Any]] = [r for r in checks.get("runs", []) if isinstance(r, dict)]
+ runs.insert(0, result)
+ del runs[MAX_CHECKS:]
+ _write_json(_checks_file(service_id, home), {"service": service_id, "runs": runs})
+
+
+def last_check(service_id: str, home: Optional[str] = None) -> Optional[Dict[str, Any]]:
+ checks = _read_json(_checks_file(service_id, home), {})
+ runs = [r for r in checks.get("runs", []) if isinstance(r, dict)]
+ return runs[0] if runs else None
+
+
+def list_checks(service_id: str, home: Optional[str] = None) -> List[Dict[str, Any]]:
+ checks = _read_json(_checks_file(service_id, home), {})
+ return [r for r in checks.get("runs", []) if isinstance(r, dict)]
+
+
+def run_check(manifest: Dict[str, Any], runner: Optional[Callable[..., Any]] = None,
+ timeout: float = CHECK_TIMEOUT_S, home: Optional[str] = None) -> Dict[str, Any]:
+ """Run the service's own ``--check`` in its root and record the outcome.
+
+ Local services only: a GitHub service's checks are its repository's CI, which
+ this gateway does not run. ``status`` is ``passed``, ``failed`` (non-zero
+ exit), or ``unavailable`` (no check configured, not local, spawn failure or
+ timeout — the ``reason`` says which)."""
+ service_id = manifest["id"]
+ started = time.monotonic()
+ checked_at = _now_iso()
+ result: Dict[str, Any] = {"checked_at": checked_at, "revision": local_revision(manifest) or "working-tree"}
+ if not manifest.get("root"):
+ result.update({"status": "unavailable", "reason": "checks for a GitHub service run in its repository's CI"})
+ elif not manifest.get("check"):
+ result.update({"status": "unavailable", "reason": "no check command declared in the manifest"})
+ else:
+ run = runner or subprocess.run
+ try:
+ completed = run(
+ manifest["check"], cwd=manifest["root"], capture_output=True, text=True, timeout=timeout,
+ )
+ output = ((completed.stdout or "") + (completed.stderr or "")).strip()
+ result.update({
+ "status": "passed" if completed.returncode == 0 else "failed",
+ "exit_code": int(completed.returncode),
+ "output": output[-MAX_CHECK_OUTPUT:],
+ })
+ except subprocess.TimeoutExpired:
+ result.update({"status": "unavailable", "reason": f"check exceeded {int(timeout)}s"})
+ except (OSError, ValueError) as exc:
+ result.update({"status": "unavailable", "reason": f"could not run check: {exc}"})
+ result["duration_s"] = round(time.monotonic() - started, 3)
+ result["command"] = list(manifest.get("check") or [])
+ record_check(service_id, result, home)
+ return result
+
+
+# ── Composite reads ──────────────────────────────────────────────────────────
+
+
+def described_deployments(manifest: Dict[str, Any]) -> List[Dict[str, Any]]:
+ """The manifest's deployments with their last known probe (never probing here)."""
+ from tui_gateway import deployments
+
+ return [
+ deployments.describe_deployment(manifest, deployment, deployments.last_probe(deployment["graph_id"]))
+ for deployment in manifest.get("deployments") or []
+ ]
+
+
+def resolved_logs(manifest: Dict[str, Any]) -> List[Dict[str, Any]]:
+ """The manifest's log sinks as clients see them: existence, size, mtime."""
+ from tui_gateway import service_logs
+
+ return service_logs.resolve_sinks(manifest)
+
+
+def status_for(manifest: Dict[str, Any], home: Optional[str] = None) -> Dict[str, Any]:
+ """The cheap annotation a service node carries: source, revision, last check."""
+ snapshots = list_snapshots(manifest["id"], home)
+ check = last_check(manifest["id"], home)
+ revision = local_revision(manifest) if manifest.get("root") else (snapshots.get("latest") or manifest["ref"])
+ annotation: Dict[str, Any] = {
+ "ref": graph_id(manifest),
+ "source": source_of(manifest),
+ "revision": revision or snapshots.get("latest") or "",
+ "model": manifest["model"],
+ "snapshots": len(snapshots.get("revisions") or []),
+ }
+ if manifest.get("runtime"):
+ annotation["runtime"] = manifest["runtime"]["graph_id"]
+ annotation["logs"] = [sink["id"] for sink in manifest.get("logs") or []]
+ if check is not None:
+ annotation["check"] = {"status": check.get("status"), "checked_at": check.get("checked_at")}
+ latest = snapshots.get("latest")
+ entry = next((r for r in snapshots.get("revisions") or [] if r.get("revision") == latest), None)
+ if entry and isinstance(entry.get("summary"), dict):
+ annotation["summary"] = entry["summary"]
+ annotation["contract"] = contract_ref()
+ annotation.update(conformance_for(manifest, snapshots, home))
+ return annotation
+
+
+def conformance_for(manifest: Dict[str, Any], snapshots: Optional[Dict[str, Any]] = None,
+ home: Optional[str] = None) -> Dict[str, Any]:
+ """``{"conforming": bool, "problem"?: str}`` for the node annotation, cheaply:
+ a local model is read and validated from its checkout (no network) AND the
+ manifest must declare at least one resolvable log sink (log capture is part
+ of the standard for local services); a GitHub model is conforming when a
+ snapshot of it was stored (snapshots are only stored for validated documents)
+ and unread until ``architecture.describe`` fetches it. Fail-open: a read
+ failure is a non-conformance with the reason; several reasons are joined."""
+ if manifest.get("root"):
+ from tui_gateway import service_logs
+
+ problems: List[str] = []
+ try:
+ read_local_model(manifest)
+ except ArchitectureError as exc:
+ problems.append(exc.message)
+ capture = service_logs.capture_problem(manifest)
+ if capture:
+ problems.append(capture)
+ if problems:
+ return {"conforming": False, "problem": "; ".join(problems)}
+ return {"conforming": True}
+ snapshots = snapshots if snapshots is not None else list_snapshots(manifest["id"], home)
+ if snapshots.get("latest"):
+ return {"conforming": True}
+ return {"conforming": False, "problem": "model not read yet; architecture.describe fetches and validates it"}
+
+
+def describe(manifest: Dict[str, Any], revision: Optional[str] = None, home: Optional[str] = None,
+ **read_kwargs: Any) -> Dict[str, Any]:
+ """The model for a service at its current revision (reading and snapshotting
+ it) or at a stored revision. Raises ArchitectureError when unavailable."""
+ service_id = manifest["id"]
+ if revision:
+ model = load_snapshot(service_id, revision, home)
+ if model is None:
+ raise ArchitectureError(4404, f"no stored revision {revision} for {service_id}")
+ source = next((r.get("source") for r in list_snapshots(service_id, home)["revisions"] if r.get("revision") == revision), source_of(manifest))
+ entry = {"revision": revision, "source": source}
+ else:
+ read = read_model(manifest, **read_kwargs)
+ model = read["model"]
+ entry = store_snapshot(service_id, read["revision"], model, read["source"], home)
+ return {
+ "service": {
+ "id": graph_id(manifest),
+ "label": manifest["name"],
+ "description": manifest["description"],
+ "source": source_of(manifest),
+ "root": manifest.get("root"),
+ "repository": manifest.get("repository"),
+ "ref": manifest.get("ref") if manifest.get("repository") else None,
+ "model_path": manifest["model"],
+ "check_configured": bool(manifest.get("check")),
+ "runtime": manifest.get("runtime"),
+ "logs": resolved_logs(manifest),
+ "deployments": described_deployments(manifest),
+ },
+ "revision": entry["revision"],
+ "source": entry.get("source", source_of(manifest)),
+ "stored_at": entry.get("stored_at"),
+ "summary": entry.get("summary") or summarize_model(model),
+ "check": last_check(service_id, home),
+ "contract": contract.describe_contract(),
+ # Whether this is the newest stored revision, so a client viewing an older
+ # snapshot can say so (architecture.history lists them all).
+ "is_latest": entry["revision"] == list_snapshots(service_id, home).get("latest"),
+ "model": model,
+ }
+
+
+# ── Revision history ─────────────────────────────────────────────────────────
+#
+# A snapshot per revision is what the store already keeps; history joins those
+# snapshots to the commits behind them (local checkouts only) and says which one
+# the checkout is at now. "Deployed" here means exactly that — the revision the
+# root is checked out at — not proof that a process restarted; a runtime
+# provider that can report a pid does so under ``runtime``.
+
+MAX_HISTORY_COMMITS = 50
+MAX_DIFF_STAT = 500
+WORKING_TREE_REVISION = "working-tree"
+_GIT_LOG_FORMAT = "%H%x1f%an%x1f%aI%x1f%s"
+
+GitRunner = Callable[..., str]
+
+
+def _run_git(root: str, *args: str) -> str:
+ """``git <args>`` in ``root``; empty string on any failure (fail-open)."""
+ try:
+ from tui_gateway.git_probe import run_git
+
+ return run_git(root, *args) or ""
+ except Exception: # pragma: no cover - probe is fail-open by contract
+ return ""
+
+
+def _is_git_revision(revision: Optional[str]) -> bool:
+ return bool(revision) and revision != WORKING_TREE_REVISION and not str(revision).startswith("sha256:")
+
+
+def _parse_commits(text: str) -> List[Dict[str, str]]:
+ commits: List[Dict[str, str]] = []
+ for line in (text or "").splitlines():
+ parts = line.split("\x1f")
+ if len(parts) != 4 or not parts[0].strip():
+ continue
+ commits.append({"sha": parts[0].strip(), "author": parts[1], "date": parts[2], "subject": parts[3]})
+ return commits
+
+
+def commit_info(root: Optional[str], revision: Optional[str], git: Optional[GitRunner] = None) -> Optional[Dict[str, str]]:
+ """``{sha, author, date, subject}`` for one revision of a local root, or None
+ when there is no root, the revision is not a git commit, or git fails."""
+ if not root or not _is_git_revision(revision):
+ return None
+ commits = _parse_commits((git or _run_git)(root, "log", "-1", f"--format={_GIT_LOG_FORMAT}", str(revision)))
+ return commits[0] if commits else None
+
+
+def commits_between(root: Optional[str], previous: Optional[str], revision: Optional[str],
+ git: Optional[GitRunner] = None) -> Optional[List[Dict[str, str]]]:
+ """The commits ``previous..revision`` oldest first, bounded at
+ ``MAX_HISTORY_COMMITS``; None when either end is not a git commit."""
+ if not root or not _is_git_revision(previous) or not _is_git_revision(revision):
+ return None
+ text = (git or _run_git)(root, "log", "--reverse", f"--max-count={MAX_HISTORY_COMMITS}",
+ f"--format={_GIT_LOG_FORMAT}", f"{previous}..{revision}")
+ return _parse_commits(text)
+
+
+def git_numstat(root: str, previous: str, revision: str, git: Optional[GitRunner] = None) -> Dict[str, Any]:
+ """``git diff --numstat previous..revision`` as ``{stat: [...], truncated}``;
+ binary files carry null counts."""
+ text = (git or _run_git)(root, "diff", "--numstat", f"{previous}..{revision}")
+ stat: List[Dict[str, Any]] = []
+ for line in (text or "").splitlines():
+ parts = line.split("\t")
+ if len(parts) != 3:
+ continue
+ additions = int(parts[0]) if parts[0].isdigit() else None
+ deletions = int(parts[1]) if parts[1].isdigit() else None
+ stat.append({"path": parts[2], "additions": additions, "deletions": deletions})
+ truncated = len(stat) > MAX_DIFF_STAT
+ return {"stat": stat[:MAX_DIFF_STAT], "truncated": truncated}
+
+
+def runtime_info(manifest: Dict[str, Any], runner: Optional[Callable[[List[str]], str]] = None) -> Optional[Dict[str, Any]]:
+ """What the runtime provider can say about the bound service: provider and
+ graph id always; for launchd the running pid when ``launchctl print`` reports
+ one (fail-open). No provider reports a start time, so ``started_at`` is
+ absent rather than guessed."""
+ binding = manifest.get("runtime")
+ if not isinstance(binding, dict):
+ return None
+ info: Dict[str, Any] = {"provider": binding.get("provider"), "graph_id": binding.get("graph_id")}
+ if binding.get("provider") == "launchd":
+ try:
+ from tools.launchd_services import _default_runner, _uid
+
+ out = (runner or _default_runner)(["launchctl", "print", f"gui/{_uid()}/{binding.get('id')}"])
+ for line in out.splitlines():
+ stripped = line.strip()
+ if stripped.startswith("pid ="):
+ value = stripped.split("=", 1)[1].strip()
+ if value.isdigit():
+ info["pid"] = int(value)
+ break
+ except Exception:
+ pass
+ return info
+
+
+def _last_deployment_probes(manifest: Dict[str, Any]) -> List[Dict[str, Any]]:
+ from tui_gateway import deployments
+
+ probes = []
+ for deployment in manifest.get("deployments") or []:
+ probe = deployments.last_probe(deployment["graph_id"])
+ if probe:
+ probes.append(probe)
+ return probes
+
+
+def history(manifest: Dict[str, Any], home: Optional[str] = None, git: Optional[GitRunner] = None,
+ runtime_runner: Optional[Callable[[List[str]], str]] = None) -> Dict[str, Any]:
+ """Stored revisions (genesis first, newest last) with the commit behind each,
+ the commits since the previous snapshot, and which one the checkout is at."""
+ service_id = manifest["id"]
+ root = manifest.get("root")
+ snapshots = list_snapshots(service_id, home)
+ revisions: List[Dict[str, Any]] = [dict(r) for r in snapshots.get("revisions") or []]
+ head = local_revision(manifest, (lambda r: (git or _run_git)(r, "rev-parse", "HEAD")) if root else None) if root else ""
+ deployed_index = None
+ for index, entry in enumerate(revisions):
+ if root and head and entry.get("revision") == head:
+ deployed_index = index # the newest match wins
+ previous: Optional[str] = None
+ for index, entry in enumerate(revisions):
+ revision = str(entry.get("revision") or "")
+ if root:
+ commit = commit_info(root, revision, git)
+ if commit:
+ entry["commit"] = commit
+ since = commits_between(root, previous, revision, git)
+ if since is not None:
+ entry["commits_since_previous"] = since
+ entry["deployed"] = index == deployed_index
+ if entry["deployed"]:
+ entry["deployed_at"] = entry.get("stored_at")
+ # Environments whose last revision probe answered with this revision.
+ live_in = [
+ probe["deployment"] for probe in _last_deployment_probes(manifest)
+ if revision and str(((probe.get("revision") or {}).get("revision")) or "").startswith(revision[:7])
+ ]
+ if live_in:
+ entry["live_in"] = sorted(live_in)
+ previous = revision
+ result: Dict[str, Any] = {
+ "service": graph_id(manifest),
+ "source": source_of(manifest),
+ "latest": snapshots.get("latest"),
+ "head": head or None,
+ "revisions": revisions,
+ "checks": list_checks(service_id, home),
+ }
+ runtime = runtime_info(manifest, runtime_runner)
+ if runtime is not None:
+ result["runtime"] = runtime
+ return result
+
+
+def _node_key(node: Dict[str, Any]) -> str:
+ return str(node.get("history_key") or node.get("id") or "")
+
+
+def _index_nodes(model: Dict[str, Any]) -> Dict[str, Dict[str, Any]]:
+ interplay = model.get("interplay") if isinstance(model.get("interplay"), dict) else {}
+ return {_node_key(n): n for n in interplay.get("nodes") or [] if isinstance(n, dict) and _node_key(n)}
+
+
+def _edge_keys(model: Dict[str, Any]) -> Dict[tuple, Dict[str, Any]]:
+ interplay = model.get("interplay") if isinstance(model.get("interplay"), dict) else {}
+ by_id = {str(n.get("id")): _node_key(n) for n in interplay.get("nodes") or [] if isinstance(n, dict)}
+ edges: Dict[tuple, Dict[str, Any]] = {}
+ for edge in interplay.get("edges") or []:
+ if not isinstance(edge, dict):
+ continue
+ source = by_id.get(str(edge.get("source")), str(edge.get("source")))
+ target = by_id.get(str(edge.get("target")), str(edge.get("target")))
+ relation = str(edge.get("relation") or "")
+ edges[(source, target, relation)] = {"source": source, "target": target, "relation": relation, "class": edge.get("class")}
+ return edges
+
+
+def _node_record(key: str, node: Dict[str, Any]) -> Dict[str, Any]:
+ return {"id": node.get("id"), "history_key": key, "kind": node.get("kind"), "label": node.get("label"), "component": node.get("component")}
+
+
+def diff_models(before: Dict[str, Any], after: Dict[str, Any]) -> Dict[str, Any]:
+ """What changed between two documents, by stable identity: nodes by history
+ key (a rename is not churn), edges by (source key, target key, relation),
+ invariants by id, files by path, gate jobs and ratchets by id."""
+ nodes_before, nodes_after = _index_nodes(before), _index_nodes(after)
+ edges_before, edges_after = _edge_keys(before), _edge_keys(after)
+
+ def invariants(model: Dict[str, Any]) -> Dict[str, str]:
+ interplay = model.get("interplay") if isinstance(model.get("interplay"), dict) else {}
+ return {str(i.get("id")): str(i.get("status") or "") for i in interplay.get("invariants") or [] if isinstance(i, dict) and i.get("id")}
+
+ def files(model: Dict[str, Any]) -> Dict[str, int]:
+ extraction = model.get("extraction") if isinstance(model.get("extraction"), dict) else {}
+ return {str(f.get("path")): int(f.get("line_count") or 0) for f in extraction.get("files") or [] if isinstance(f, dict) and f.get("path")}
+
+ def ids(model: Dict[str, Any], key: str) -> set:
+ ci = model.get("ci") if isinstance(model.get("ci"), dict) else {}
+ return {str(item.get("id")) for item in ci.get(key) or [] if isinstance(item, dict) and item.get("id")}
+
+ inv_before, inv_after = invariants(before), invariants(after)
+ files_before, files_after = files(before), files(after)
+ return {
+ "nodes": {
+ "added": [_node_record(k, nodes_after[k]) for k in sorted(set(nodes_after) - set(nodes_before))],
+ "removed": [_node_record(k, nodes_before[k]) for k in sorted(set(nodes_before) - set(nodes_after))],
+ },
+ "edges": {
+ "added": [edges_after[k] for k in sorted(set(edges_after) - set(edges_before))],
+ "removed": [edges_before[k] for k in sorted(set(edges_before) - set(edges_after))],
+ },
+ "invariants": {
+ "added": sorted(set(inv_after) - set(inv_before)),
+ "removed": sorted(set(inv_before) - set(inv_after)),
+ "changed": [{"id": i, "from": inv_before[i], "to": inv_after[i]} for i in sorted(set(inv_before) & set(inv_after)) if inv_before[i] != inv_after[i]],
+ },
+ "files": {
+ "added": sorted(set(files_after) - set(files_before)),
+ "removed": sorted(set(files_before) - set(files_after)),
+ "changed": [{"path": p, "lines_from": files_before[p], "lines_to": files_after[p]}
+ for p in sorted(set(files_before) & set(files_after)) if files_before[p] != files_after[p]],
+ },
+ "gates": {
+ "jobs_added": sorted(ids(after, "jobs") - ids(before, "jobs")),
+ "jobs_removed": sorted(ids(before, "jobs") - ids(after, "jobs")),
+ "ratchets_added": sorted(ids(after, "ratchets") - ids(before, "ratchets")),
+ "ratchets_removed": sorted(ids(before, "ratchets") - ids(after, "ratchets")),
+ },
+ "summary": {"from": summarize_model(before), "to": summarize_model(after)},
+ }
+
+
+def diff(manifest: Dict[str, Any], from_revision: Optional[str] = None, to_revision: Optional[str] = None,
+ home: Optional[str] = None, git: Optional[GitRunner] = None) -> Dict[str, Any]:
+ """The structural diff between two stored revisions; ``to`` defaults to the
+ latest snapshot and ``from`` to the one stored before it. 4404 when a
+ revision is not stored or there is nothing before ``to``. For a local root
+ the commits and ``git diff --numstat`` between the two are attached (fail-open)."""
+ service_id = manifest["id"]
+ snapshots = list_snapshots(service_id, home)
+ order = [str(r.get("revision")) for r in snapshots.get("revisions") or []]
+ to_rev = to_revision or snapshots.get("latest")
+ if not to_rev or to_rev not in order:
+ raise ArchitectureError(4404, f"no stored revision {to_rev or '(latest)'} for {service_id}")
+ if from_revision:
+ from_rev = from_revision
+ else:
+ position = order.index(to_rev)
+ if position == 0:
+ raise ArchitectureError(4404, f"no stored revision before {to_rev} for {service_id}")
+ from_rev = order[position - 1]
+ before = load_snapshot(service_id, from_rev, home)
+ after = load_snapshot(service_id, to_rev, home)
+ if before is None:
+ raise ArchitectureError(4404, f"no stored revision {from_rev} for {service_id}")
+ if after is None:
+ raise ArchitectureError(4404, f"no stored revision {to_rev} for {service_id}")
+ result: Dict[str, Any] = {"service": graph_id(manifest), "from": from_rev, "to": to_rev}
+ result.update(diff_models(before, after))
+ root = manifest.get("root")
+ if root and _is_git_revision(from_rev) and _is_git_revision(to_rev):
+ commits = commits_between(root, from_rev, to_rev, git) or []
+ numstat = git_numstat(root, from_rev, to_rev, git)
+ result["git"] = {"commits": commits, "stat": numstat["stat"],
+ "truncated": numstat["truncated"] or len(commits) >= MAX_HISTORY_COMMITS}
+ return result
diff --git hermes-agent/tui_gateway/deployments.py harness/tui_gateway/deployments.py
new file mode 100644
index 0000000000000000000000000000000000000000..5379b32edffdd88de2bb26b60065fa2b48fdffcd
--- /dev/null
+++ harness/tui_gateway/deployments.py
@@ -0,0 +1,506 @@
+"""Deployments: where a service's code runs when it is not on this machine.
+
+The runtime providers (process, Docker, Nomad, launchd) answer "is it live, what
+is live, show me its logs" for services on the gateway host. A Lambda, a Cloud
+Run revision, an ECS service or a Fly app has no process, port or container the
+gateway can see, so until now such a service could only be a standalone
+``arch:<id>`` codebase node: the code was drawn, never whether it was up.
+
+A manifest may now declare ``deployments``: one entry per environment the
+codebase is deployed to, each with a provider name, a target, an explicit
+**health probe**, an optional **revision probe** and its own **log sinks**. The
+probes are the deployment's own declaration of how to ask — an HTTPS endpoint
+with an expected status, or a bounded command whose exit code answers — never a
+provider SDK the gateway has to carry. Logs use the ``command`` sink kind
+(``aws logs tail``, ``gcloud logging read``, ``flyctl logs``), bounded like every
+other read here. Each deployment is a graph node of its own
+(``deploy:<manifest-id>/<deployment-id>``) beside the codebase node, so staging
+and production are two nodes with two healths, both pointing back at the model.
+
+Probing is explicit and cheap to reason about: ``service.deployments.probe`` runs
+the probes now; the graph and ``architecture.describe`` read the last known
+result (or probe once with a short timeout when nothing is known yet), never a
+guess. Results are cached in memory for ``CACHE_TTL_S`` so a graph refresh does
+not hammer a health endpoint. Only declared URLs and argv are ever contacted or
+run — never a caller-supplied one.
+
+Manifest shape::
+
+ "deployments": [
+ {
+ "id": "prod", # unique per manifest
+ "environment": "production", # label; defaults to id
+ "provider": "aws-lambda", # free-form token: aws-lambda, ecs, cloud-run, fly, vercel, kubernetes, …
+ "target": "arn:aws:lambda:us-east-1:…:function:demo",
+ "url": "https://demo.example.com", # optional; drawn as an output
+ "health": {"kind": "https", "url": "https://demo.example.com/healthz", "expect": [200, 204], "timeout_s": 5},
+ "revision": {"kind": "command", "argv": ["aws", "lambda", "get-function-configuration", "--function-name", "demo", "--query", "Version", "--output", "text"]},
+ "logs": [{"id": "cloudwatch", "kind": "command", "argv": ["aws", "logs", "tail", "/aws/lambda/demo", "--since", "15m", "--format", "short"]}]
+ }
+ ]
+
+``health.kind`` is ``https`` (GET the URL; live when the status is in ``expect``,
+default ``200``) or ``command`` (run argv without a shell; live on exit 0).
+``revision.kind`` is ``command`` (first non-empty stdout line is the live
+revision) or ``https`` (GET; the body, or ``json_path`` into a JSON body).
+"""
+from __future__ import annotations
+
+import json
+import logging
+import re
+import shlex
+import shutil
+import subprocess
+import threading
+import time
+import urllib.error
+import urllib.request
+from concurrent.futures import ThreadPoolExecutor, as_completed
+from datetime import datetime, timezone
+from typing import Any, Callable, Dict, List, Optional
+
+logger = logging.getLogger(__name__)
+
+ID_PREFIX = "deploy:"
+DEPLOYMENT_ID_RE = re.compile(r"^[a-z0-9][a-z0-9._-]{0,63}$")
+PROVIDER_RE = re.compile(r"^[a-z][a-z0-9-]{0,31}$")
+HEALTH_KINDS = ("https", "command")
+REVISION_KINDS = ("https", "command")
+DEFAULT_TIMEOUT_S = 5.0
+MAX_TIMEOUT_S = 60.0
+DEFAULT_EXPECT = (200,)
+MAX_BODY_BYTES = 256 * 1024
+# How long a probe result stands in for a fresh one on the graph and in describe.
+CACHE_TTL_S = 30.0
+STATUSES = ("live", "down", "unknown")
+
+
+class DeploymentError(Exception):
+ def __init__(self, code: int, message: str) -> None:
+ super().__init__(message)
+ self.code = code
+ self.message = message
+
+
+# ── Declaration ──────────────────────────────────────────────────────────────
+
+def _timeout(value: Any, field: str) -> float:
+ if value is None:
+ return DEFAULT_TIMEOUT_S
+ if isinstance(value, bool) or not isinstance(value, (int, float)) or value <= 0:
+ raise ValueError(f"{field}.timeout_s must be a positive number of seconds")
+ return float(min(value, MAX_TIMEOUT_S))
+
+
+def _argv(value: Any, field: str) -> List[str]:
+ if isinstance(value, str):
+ value = shlex.split(value)
+ if not isinstance(value, list) or not value or not all(isinstance(part, str) and part.strip() for part in value):
+ raise ValueError(f"{field}.argv must be a non-empty list of strings")
+ return [part.strip() for part in value]
+
+
+def _https_url(value: Any, field: str) -> str:
+ if not isinstance(value, str) or not value.strip():
+ raise ValueError(f"{field}.url is required")
+ url = value.strip()
+ if not (url.startswith("https://") or url.startswith("http://localhost") or url.startswith("http://127.0.0.1")):
+ raise ValueError(f"{field}.url must be https:// (plain http is allowed for localhost only)")
+ return url
+
+
+def normalize_health(value: Any, field: str = "health") -> Dict[str, Any]:
+ if not isinstance(value, dict):
+ raise ValueError(f"{field} must be an object with kind https or command")
+ kind = value.get("kind")
+ if kind not in HEALTH_KINDS:
+ raise ValueError(f"{field}.kind must be one of {', '.join(HEALTH_KINDS)}")
+ probe: Dict[str, Any] = {"kind": kind, "timeout_s": _timeout(value.get("timeout_s"), field)}
+ if kind == "https":
+ probe["url"] = _https_url(value.get("url"), field)
+ expect = value.get("expect", list(DEFAULT_EXPECT))
+ if isinstance(expect, int) and not isinstance(expect, bool):
+ expect = [expect]
+ if not isinstance(expect, list) or not expect or not all(isinstance(code, int) and not isinstance(code, bool) and 100 <= code <= 599 for code in expect):
+ raise ValueError(f"{field}.expect must be an HTTP status or a list of statuses")
+ probe["expect"] = sorted(set(expect))
+ else:
+ probe["argv"] = _argv(value.get("argv"), field)
+ return probe
+
+
+def normalize_revision(value: Any, field: str = "revision") -> Dict[str, Any]:
+ if not isinstance(value, dict):
+ raise ValueError(f"{field} must be an object with kind https or command")
+ kind = value.get("kind")
+ if kind not in REVISION_KINDS:
+ raise ValueError(f"{field}.kind must be one of {', '.join(REVISION_KINDS)}")
+ probe: Dict[str, Any] = {"kind": kind, "timeout_s": _timeout(value.get("timeout_s"), field)}
+ if kind == "https":
+ probe["url"] = _https_url(value.get("url"), field)
+ json_path = value.get("json_path")
+ if json_path is not None:
+ if not isinstance(json_path, str) or not json_path.strip():
+ raise ValueError(f"{field}.json_path must be a dotted key path")
+ probe["json_path"] = json_path.strip()
+ else:
+ probe["argv"] = _argv(value.get("argv"), field)
+ return probe
+
+
+def normalize_deployments(value: Any, manifest_id: str) -> List[Dict[str, Any]]:
+ """Validate ``deployments`` from a manifest. Raises ValueError with a reason.
+ Log sinks are validated by ``service_logs.normalize_log_sinks`` with no
+ runtime binding, so launchd kinds are refused and ``command`` is allowed."""
+ if value is None:
+ return []
+ if not isinstance(value, list):
+ raise ValueError("deployments must be a list of {id, provider, target, health, …}")
+ from tui_gateway import service_logs
+
+ deployments: List[Dict[str, Any]] = []
+ seen: set = set()
+ for index, raw in enumerate(value):
+ if not isinstance(raw, dict):
+ raise ValueError(f"deployments[{index}] must be an object")
+ dep_id = raw.get("id")
+ if not isinstance(dep_id, str) or not DEPLOYMENT_ID_RE.match(dep_id):
+ raise ValueError(f"deployments[{index}].id must match ^[a-z0-9][a-z0-9._-]{{0,63}}$")
+ if dep_id in seen:
+ raise ValueError(f"deployments: duplicate id {dep_id!r}")
+ seen.add(dep_id)
+ field = f"deployments[{dep_id}]"
+ provider = raw.get("provider")
+ if not isinstance(provider, str) or not PROVIDER_RE.match(provider):
+ raise ValueError(f"{field}.provider must be a lowercase token such as aws-lambda, cloud-run, fly")
+ target = raw.get("target")
+ if not isinstance(target, str) or not target.strip():
+ raise ValueError(f"{field}.target is required (the provider's own identity for the deployment)")
+ environment = raw.get("environment", dep_id)
+ if not isinstance(environment, str) or not environment.strip():
+ raise ValueError(f"{field}.environment must be a non-empty string")
+ url = raw.get("url")
+ if url is not None:
+ url = _https_url(url, field)
+ if raw.get("health") is None:
+ raise ValueError(f"{field}.health is required: a deployment the gateway cannot probe cannot be drawn as live or down")
+ deployment: Dict[str, Any] = {
+ "id": dep_id,
+ "graph_id": f"{ID_PREFIX}{manifest_id}/{dep_id}",
+ "environment": environment.strip(),
+ "provider": provider,
+ "target": target.strip(),
+ "url": url,
+ "health": normalize_health(raw["health"], f"{field}.health"),
+ "revision": normalize_revision(raw["revision"], f"{field}.revision") if raw.get("revision") is not None else None,
+ "logs": service_logs.normalize_log_sinks(raw.get("logs"), None, None, allow_command=True),
+ }
+ deployments.append(deployment)
+ return deployments
+
+
+def parse_graph_id(graph_id: str) -> Optional[tuple]:
+ """``deploy:<manifest>/<deployment>`` → (manifest_id, deployment_id), else None."""
+ if not isinstance(graph_id, str) or not graph_id.startswith(ID_PREFIX):
+ return None
+ rest = graph_id[len(ID_PREFIX):]
+ if "/" not in rest:
+ return None
+ manifest_id, dep_id = rest.split("/", 1)
+ if not manifest_id or not dep_id:
+ return None
+ return manifest_id, dep_id
+
+
+def find_deployment(manifest: Dict[str, Any], dep_id: str) -> Optional[Dict[str, Any]]:
+ for deployment in manifest.get("deployments") or []:
+ if deployment.get("id") == dep_id:
+ return deployment
+ return None
+
+
+# ── Probing ──────────────────────────────────────────────────────────────────
+
+def _now() -> str:
+ return datetime.now(timezone.utc).replace(microsecond=0).isoformat().replace("+00:00", "Z")
+
+
+def _http_get(url: str, timeout: float) -> tuple:
+ """(status, body_text) for a GET; HTTP errors are statuses, not exceptions."""
+ request = urllib.request.Request(url, headers={"User-Agent": "hermes-gateway-deployment-probe/1.0"}, method="GET")
+ try:
+ with urllib.request.urlopen(request, timeout=timeout) as response: # noqa: S310 - declared URL only
+ body = response.read(MAX_BODY_BYTES)
+ return int(response.status), body.decode("utf-8", errors="replace")
+ except urllib.error.HTTPError as exc:
+ body = exc.read(MAX_BODY_BYTES) if exc.fp else b""
+ return int(exc.code), body.decode("utf-8", errors="replace")
+
+
+def run_argv(argv: List[str], timeout: float) -> subprocess.CompletedProcess:
+ """A bounded, shell-less run of a declared command. The executable must exist
+ on PATH or be an absolute path; otherwise the caller reports it as unknown."""
+ if not shutil.which(argv[0]):
+ raise FileNotFoundError(argv[0])
+ return subprocess.run(argv, capture_output=True, text=True, timeout=timeout, check=False, stdin=subprocess.DEVNULL) # noqa: S603 - declared argv only
+
+
+def probe_health(probe: Dict[str, Any], runner: Callable[[List[str], float], subprocess.CompletedProcess] = run_argv,
+ http_get: Callable[[str, float], tuple] = _http_get) -> Dict[str, Any]:
+ """``{status, probe, target, checked_at, latency_ms, message}`` — the same shape
+ the Docker provider's health carries. Never raises: a probe that cannot run
+ is ``unknown`` with the reason."""
+ started = time.monotonic()
+ result: Dict[str, Any] = {"status": "unknown", "probe": probe["kind"], "checked_at": _now(), "latency_ms": 0, "message": ""}
+ try:
+ if probe["kind"] == "https":
+ result["target"] = probe["url"]
+ status, _body = http_get(probe["url"], probe["timeout_s"])
+ live = status in set(probe.get("expect") or DEFAULT_EXPECT)
+ result["status"] = "live" if live else "down"
+ result["message"] = f"GET {probe['url']} → {status}" + ("" if live else f" (expected {', '.join(map(str, probe.get('expect') or DEFAULT_EXPECT))})")
+ else:
+ result["target"] = " ".join(shlex.quote(part) for part in probe["argv"])
+ completed = runner(probe["argv"], probe["timeout_s"])
+ result["status"] = "live" if completed.returncode == 0 else "down"
+ tail = (completed.stderr or completed.stdout or "").strip().splitlines()
+ result["message"] = f"exit {completed.returncode}" + (f": {tail[-1][:200]}" if tail else "")
+ except FileNotFoundError as exc:
+ result["message"] = f"command not found: {exc}"
+ except subprocess.TimeoutExpired:
+ result["status"] = "down"
+ result["message"] = f"probe timed out after {probe['timeout_s']:g}s"
+ except (urllib.error.URLError, OSError, ValueError) as exc:
+ result["status"] = "down"
+ result["message"] = f"{type(exc).__name__}: {exc}"
+ except Exception as exc: # pragma: no cover - defensive; a probe must never break the graph
+ result["message"] = f"{type(exc).__name__}: {exc}"
+ result["latency_ms"] = int((time.monotonic() - started) * 1000)
+ return result
+
+
+def _json_path(document: Any, path: str) -> Any:
+ current = document
+ for key in path.split("."):
+ if isinstance(current, dict):
+ current = current.get(key)
+ elif isinstance(current, list) and key.isdigit() and int(key) < len(current):
+ current = current[int(key)]
+ else:
+ return None
+ return current
+
+
+def probe_revision(probe: Dict[str, Any], runner: Callable[[List[str], float], subprocess.CompletedProcess] = run_argv,
+ http_get: Callable[[str, float], tuple] = _http_get) -> Dict[str, Any]:
+ """``{revision, checked_at, message}`` — ``revision`` is None when the probe
+ could not answer, with the reason in ``message``. Never raises."""
+ result: Dict[str, Any] = {"revision": None, "checked_at": _now(), "message": ""}
+ try:
+ if probe["kind"] == "https":
+ status, body = http_get(probe["url"], probe["timeout_s"])
+ if status != 200:
+ result["message"] = f"GET {probe['url']} → {status}"
+ return result
+ text = body.strip()
+ if probe.get("json_path"):
+ try:
+ value = _json_path(json.loads(text), probe["json_path"])
+ except ValueError:
+ result["message"] = "body is not JSON"
+ return result
+ text = "" if value is None else str(value)
+ result["revision"] = text.splitlines()[0].strip()[:128] if text else None
+ if result["revision"] is None:
+ result["message"] = "empty revision"
+ else:
+ completed = runner(probe["argv"], probe["timeout_s"])
+ if completed.returncode != 0:
+ result["message"] = f"exit {completed.returncode}: {(completed.stderr or '').strip()[:200]}"
+ return result
+ lines = [line.strip() for line in (completed.stdout or "").splitlines() if line.strip()]
+ result["revision"] = lines[0][:128] if lines else None
+ if result["revision"] is None:
+ result["message"] = "command printed no revision"
+ except FileNotFoundError as exc:
+ result["message"] = f"command not found: {exc}"
+ except subprocess.TimeoutExpired:
+ result["message"] = f"probe timed out after {probe['timeout_s']:g}s"
+ except (urllib.error.URLError, OSError, ValueError) as exc:
+ result["message"] = f"{type(exc).__name__}: {exc}"
+ except Exception as exc: # pragma: no cover - defensive
+ result["message"] = f"{type(exc).__name__}: {exc}"
+ return result
+
+
+# ── Cache ────────────────────────────────────────────────────────────────────
+
+_cache: Dict[str, Dict[str, Any]] = {}
+_cache_lock = threading.Lock()
+
+
+def last_probe(graph_id: str) -> Optional[Dict[str, Any]]:
+ with _cache_lock:
+ entry = _cache.get(graph_id)
+ return dict(entry) if entry else None
+
+
+def _remember(graph_id: str, payload: Dict[str, Any]) -> None:
+ with _cache_lock:
+ _cache[graph_id] = {**payload, "_at": time.monotonic()}
+
+
+def _fresh(graph_id: str, ttl: float) -> Optional[Dict[str, Any]]:
+ with _cache_lock:
+ entry = _cache.get(graph_id)
+ if entry and time.monotonic() - entry.get("_at", 0.0) <= ttl:
+ return {k: v for k, v in entry.items() if k != "_at"}
+ return None
+
+
+def reset_cache() -> None:
+ with _cache_lock:
+ _cache.clear()
+
+
+def probe_deployment(manifest: Dict[str, Any], deployment: Dict[str, Any], *, force: bool = False, ttl: float = CACHE_TTL_S,
+ runner: Callable[[List[str], float], subprocess.CompletedProcess] = run_argv,
+ http_get: Callable[[str, float], tuple] = _http_get) -> Dict[str, Any]:
+ """Health and revision for one deployment: the cached result when fresh
+ (unless ``force``), else probed now and remembered."""
+ graph_id = deployment["graph_id"]
+ if not force:
+ cached = _fresh(graph_id, ttl)
+ if cached is not None:
+ return cached
+ health = probe_health(deployment["health"], runner, http_get)
+ health["target"] = health.get("target") or deployment["target"]
+ revision = probe_revision(deployment["revision"], runner, http_get) if deployment.get("revision") else None
+ payload = {
+ "service": graph_id,
+ "manifest": manifest["id"],
+ "deployment": deployment["id"],
+ "environment": deployment["environment"],
+ "provider": deployment["provider"],
+ "target": deployment["target"],
+ "url": deployment.get("url"),
+ "health": health,
+ "revision": revision,
+ }
+ _remember(graph_id, payload)
+ return {k: v for k, v in payload.items()}
+
+
+def probe_manifest(manifest: Dict[str, Any], *, deployment_id: Optional[str] = None, force: bool = False,
+ ttl: float = CACHE_TTL_S) -> List[Dict[str, Any]]:
+ """Probe every deployment of a manifest (or one), concurrently, in id order."""
+ targets = [d for d in manifest.get("deployments") or [] if deployment_id is None or d["id"] == deployment_id]
+ if deployment_id is not None and not targets:
+ raise DeploymentError(4050, f"{manifest['id']} has no deployment {deployment_id!r}")
+ if not targets:
+ return []
+ results: Dict[str, Dict[str, Any]] = {}
+ with ThreadPoolExecutor(max_workers=min(8, len(targets))) as pool:
+ futures = {pool.submit(probe_deployment, manifest, d, force=force, ttl=ttl): d["id"] for d in targets}
+ for future in as_completed(futures):
+ results[futures[future]] = future.result()
+ return [results[d["id"]] for d in targets]
+
+
+# ── Declarations for the dataflow graph ──────────────────────────────────────
+
+def describe_deployment(manifest: Dict[str, Any], deployment: Dict[str, Any], probe: Optional[Dict[str, Any]]) -> Dict[str, Any]:
+ """The deployment as ``architecture.describe`` and ``service.deployments``
+ report it: the declaration plus the last known probe (or none)."""
+ from tui_gateway import service_logs
+
+ return {
+ "id": deployment["id"],
+ "graph_id": deployment["graph_id"],
+ "environment": deployment["environment"],
+ "provider": deployment["provider"],
+ "target": deployment["target"],
+ "url": deployment.get("url"),
+ "health_probe": deployment["health"],
+ "revision_probe": deployment.get("revision"),
+ "logs": [service_logs.resolve_sink(sink) for sink in deployment.get("logs") or []],
+ "health": (probe or {}).get("health"),
+ "revision": ((probe or {}).get("revision") or {}).get("revision") if probe else None,
+ "probed_at": ((probe or {}).get("health") or {}).get("checked_at") if probe else None,
+ }
+
+
+def _markdown(manifest: Dict[str, Any], deployment: Dict[str, Any], probe: Dict[str, Any]) -> str:
+ health = probe.get("health") or {}
+ revision = (probe.get("revision") or {}).get("revision")
+ lines = [
+ f"**{manifest['name']}** deployed to **{deployment['environment']}** on `{deployment['provider']}`.",
+ "",
+ f"- target: `{deployment['target']}`",
+ ]
+ if deployment.get("url"):
+ lines.append(f"- url: {deployment['url']}")
+ lines.append(f"- health: **{health.get('status', 'unknown')}** — {health.get('message') or 'not probed yet'}")
+ if deployment.get("revision"):
+ lines.append(f"- live revision: `{revision}`" if revision else "- live revision: unknown")
+ if deployment.get("logs"):
+ lines.append(f"- logs: {', '.join(sink['label'] for sink in deployment['logs'])} (`service.logs` on `{deployment['graph_id']}`)")
+ return "\n".join(lines)
+
+
+def collect_deployment_services(home: Optional[str] = None, *, probe: bool = True) -> List[Dict[str, Any]]:
+ """One graph service declaration per declared deployment, with its health.
+ ``probe=False`` uses only what is already known (tests, cheap listings)."""
+ from cron.jobs import normalize_service_declaration
+ from tui_gateway import architecture_store as store
+
+ services: List[Dict[str, Any]] = []
+ for manifest in store.list_manifests(home):
+ deployments = manifest.get("deployments") or []
+ if not deployments:
+ continue
+ probes: Dict[str, Dict[str, Any]] = {}
+ if probe:
+ try:
+ for result in probe_manifest(manifest):
+ probes[result["deployment"]] = result
+ except Exception:
+ logger.exception("deployment probes failed for %s", manifest["id"])
+ annotation = store.status_for(manifest, home)
+ for deployment in deployments:
+ result = probes.get(deployment["id"]) or last_probe(deployment["graph_id"]) or {}
+ health = dict(result.get("health") or {"status": "unknown", "probe": deployment["health"]["kind"],
+ "target": deployment["target"], "checked_at": "", "latency_ms": 0,
+ "message": "not probed yet"})
+ try:
+ declaration = normalize_service_declaration(
+ f"{manifest['name']} · {deployment['environment']}",
+ _markdown(manifest, deployment, result),
+ inputs=[],
+ outputs=[deployment["url"]] if deployment.get("url") else [],
+ side_effects=[],
+ relationships=[{"predicate": "deploys", "object": store.graph_id(manifest)}],
+ source_files=[],
+ )
+ except ValueError as exc:
+ logger.warning("deployment %s rejected: %s", deployment["graph_id"], exc)
+ continue
+ services.append({
+ "id": deployment["graph_id"],
+ "label": declaration["name"],
+ "description": declaration["description"],
+ "inputs": declaration["inputs"],
+ "outputs": declaration["outputs"],
+ "side_effects": declaration["side_effects"],
+ "relationships": declaration.get("relationships") or [],
+ "source_files": [],
+ "health": health,
+ "deployment": {
+ "manifest": manifest["id"], "id": deployment["id"], "environment": deployment["environment"],
+ "provider": deployment["provider"], "target": deployment["target"], "url": deployment.get("url"),
+ "revision": ((result.get("revision") or {}).get("revision")) if result else None,
+ },
+ "architecture": {**annotation, "deployment": deployment["graph_id"]},
+ })
+ return services
diff --git hermes-agent/tui_gateway/methods_architecture.py harness/tui_gateway/methods_architecture.py
new file mode 100644
index 0000000000000000000000000000000000000000..090408871aac06f444ecf2bac175a44aab832e7b
--- /dev/null
+++ harness/tui_gateway/methods_architecture.py
@@ -0,0 +1,172 @@
+"""``architecture.*`` — per-service architecture models over JSON-RPC.
+
+A service declared by a manifest under ``~/.hermes/services/architecture/`` has
+a compiler-emitted architecture model (system map, invariants, stores,
+externals, CI plane). These handlers read it, snapshot it per revision, run the
+service's own ``--check`` on demand, and list what was recorded — for a local
+checkout that is never pushed as much as for a GitHub repository. Portal opens
+the model from the service node on the dataflow graph. Contract: docs/api/architecture.md.
+Log sinks a manifest declares are read by ``service.logs`` (methods_service.py).
+"""
+from __future__ import annotations
+
+from .method_ctx import HandlerRegistry
+
+_registry = HandlerRegistry()
+method = _registry.method
+
+# No module-level helpers below: ``HandlerRegistry.install`` rebinds each handler's
+# globals to the server module, so anything a body needs must be imported inside
+# it (``architecture_store.service_param``) or be a server global (``_ok``).
+
+
+@method("architecture.list")
+def _(rid, params: dict) -> dict:
+ """Every manifest-declared service with its source, revision, last check and
+ whether its model conforms to the hermes.architecture contract."""
+ try:
+ from tui_gateway import architecture_store as store
+
+ services = []
+ for manifest in store.list_manifests():
+ services.append({
+ "id": store.graph_id(manifest),
+ "label": manifest["name"],
+ "description": manifest["description"],
+ "source": store.source_of(manifest),
+ "root": manifest.get("root"),
+ "repository": manifest.get("repository"),
+ "ref": manifest.get("ref") if manifest.get("repository") else None,
+ "model": manifest["model"],
+ "check_configured": bool(manifest.get("check")),
+ "runtime": manifest.get("runtime"),
+ "logs": store.resolved_logs(manifest),
+ "status": store.status_for(manifest),
+ })
+ # status carries each service's contract + conforming; the list names the
+ # contract this gateway validates against so a client can feature-gate once.
+ return _ok(rid, {"services": services, "contract": store.contract_ref()})
+ except Exception as e:
+ logger.exception("architecture.list failed")
+ return _err(rid, 5040, str(e))
+
+
+@method("architecture.describe")
+def _(rid, params: dict) -> dict:
+ """The model for one service: its current revision (read now, validated
+ against the contract and snapshotted) or a stored ``revision``. A document
+ that does not conform is refused with 4033 and the message names the first
+ problems. A newly seen revision is announced as ``architecture.changed``."""
+ try:
+ from tui_gateway import architecture_store as store
+
+ service_id = store.service_param(params)
+ if service_id is None:
+ return _err(rid, 4029, "architecture.describe needs a 'service' id")
+ manifest = store.load_manifest(service_id)
+ if manifest is None:
+ return _err(rid, 4030, f"unknown service: {service_id}")
+ revision = (params or {}).get("revision")
+ revision = revision.strip() if isinstance(revision, str) and revision.strip() else None
+ before = store.list_snapshots(manifest["id"]).get("latest")
+ try:
+ document = store.describe(manifest, revision=revision)
+ except store.ArchitectureError as exc:
+ return _err(rid, exc.code, exc.message)
+ if revision is None and document["revision"] != before:
+ _broadcast_global_event("architecture.changed", {
+ "service": document["service"]["id"],
+ "revision": document["revision"],
+ "source": document["source"],
+ "reason": "snapshot",
+ })
+ return _ok(rid, document)
+ except Exception as e:
+ logger.exception("architecture.describe failed")
+ return _err(rid, 5041, str(e))
+
+
+@method("architecture.check")
+def _(rid, params: dict) -> dict:
+ """Run the service's own ``--check`` in its root and record the result. Local
+ services only; a GitHub service reports ``unavailable`` because its checks run
+ in its repository's CI. The outcome is announced as ``architecture.changed``."""
+ try:
+ from tui_gateway import architecture_store as store
+
+ service_id = store.service_param(params)
+ if service_id is None:
+ return _err(rid, 4029, "architecture.check needs a 'service' id")
+ manifest = store.load_manifest(service_id)
+ if manifest is None:
+ return _err(rid, 4030, f"unknown service: {service_id}")
+ result = store.run_check(manifest)
+ # Only a check that ran is news; "unavailable" changes nothing a client shows.
+ if result.get("status") in ("passed", "failed"):
+ _broadcast_global_event("architecture.changed", {
+ "service": store.graph_id(manifest),
+ "revision": result.get("revision"),
+ "source": store.source_of(manifest),
+ "reason": "check",
+ "status": result.get("status"),
+ })
+ return _ok(rid, {"service": store.graph_id(manifest), "check": result})
+ except Exception as e:
+ logger.exception("architecture.check failed")
+ return _err(rid, 5042, str(e))
+
+
+@method("architecture.history")
+def _(rid, params: dict) -> dict:
+ """Stored revisions (genesis first, newest last) with the commit behind each
+ and the commits since the previous snapshot (local roots), which revision the
+ checkout is at now (``deployed``), the runtime provider's view when bound,
+ and recorded check runs."""
+ try:
+ from tui_gateway import architecture_store as store
+
+ service_id = store.service_param(params)
+ if service_id is None:
+ return _err(rid, 4029, "architecture.history needs a 'service' id")
+ manifest = store.load_manifest(service_id)
+ if manifest is None:
+ return _err(rid, 4030, f"unknown service: {service_id}")
+ return _ok(rid, store.history(manifest))
+ except Exception as e:
+ logger.exception("architecture.history failed")
+ return _err(rid, 5043, str(e))
+
+
+@method("architecture.diff")
+def _(rid, params: dict) -> dict:
+ """What changed between two stored revisions: constructions, edges,
+ invariants, files, gates (by stable identity) and, for a local root, the
+ commits and per-file line counts between them. ``to`` defaults to the latest
+ snapshot, ``from`` to the one before it."""
+ try:
+ from tui_gateway import architecture_store as store
+
+ service_id = store.service_param(params)
+ if service_id is None:
+ return _err(rid, 4029, "architecture.diff needs a 'service' id")
+ manifest = store.load_manifest(service_id)
+ if manifest is None:
+ return _err(rid, 4030, f"unknown service: {service_id}")
+ params = params or {}
+ ends = {}
+ for key in ("from", "to"):
+ value = params.get(key)
+ if value is not None and (not isinstance(value, str) or not value.strip()):
+ return _err(rid, 4001, f"architecture.diff '{key}' must be a non-empty revision string")
+ ends[key] = value.strip() if isinstance(value, str) else None
+ try:
+ return _ok(rid, store.diff(manifest, ends["from"], ends["to"]))
+ except store.ArchitectureError as exc:
+ return _err(rid, exc.code, exc.message)
+ except Exception as e:
+ logger.exception("architecture.diff failed")
+ return _err(rid, 5044, str(e))
+
+
+def register(server) -> None:
+ _registry.install(server)
diff --git hermes-agent/tui_gateway/methods_service.py harness/tui_gateway/methods_service.py
new file mode 100644
index 0000000000000000000000000000000000000000..d9363681b6f57736f50614830f920d8fdaad1b63
--- /dev/null
+++ harness/tui_gateway/methods_service.py
@@ -0,0 +1,150 @@
+"""``service.*`` — what a running service exposes beyond its dataflow node.
+
+Its logs: ``service.logs`` tails or continues one of a service's log sinks and
+``service.logs.follow`` streams appended lines as ``service.log`` events. The
+``service`` param is a graph service id (``arch:<id>``, ``deploy:<id>/<env>``,
+``launchd:<label>``, ``docker:<12>``, ``nomad:<job>``, ``proc_<id>``); sinks
+resolve per provider in ``tui_gateway/service_logs.py``, and only those paths
+and declared commands are ever read or run. Docs: docs/api/service-logs.md.
+
+Its deployments: ``service.deployments`` lists a manifest's declared deployments
+with their last known health and revision; ``service.deployments.probe`` runs
+the declared probes now. Docs: docs/api/architecture.md (Deployments).
+"""
+from __future__ import annotations
+
+from .method_ctx import HandlerRegistry
+
+_registry = HandlerRegistry()
+method = _registry.method
+
+# No module-level helpers below: ``HandlerRegistry.install`` rebinds each handler's
+# globals to the server module, so anything a body needs must be imported inside
+# it or be a server global (``_ok``, ``_err``, ``_broadcast_global_event``).
+
+
+@method("service.logs")
+def _(rid, params: dict) -> dict:
+ """A bounded read of one log sink of a service: without a ``cursor`` the last
+ ``lines`` complete lines (default 200, max 2000) and the cursor to continue
+ from; with one, every complete line appended since. Only the sinks the
+ service resolves to are ever read. **4040** unknown sink (or none), **4041**
+ the sink has no file yet, **4042** provider without log capture, **4001** bad params."""
+ try:
+ from tui_gateway import service_logs as logs
+
+ service = (params or {}).get("service") if isinstance(params, dict) else None
+ if not isinstance(service, str) or not service.strip():
+ return _err(rid, 4029, "service.logs needs a 'service' graph id")
+ service = service.strip()
+ sink_id = (params or {}).get("sink")
+ sink_id = sink_id.strip() if isinstance(sink_id, str) and sink_id.strip() else None
+ try:
+ lines = logs.parse_lines((params or {}).get("lines"))
+ cursor = logs.parse_cursor((params or {}).get("cursor"))
+ sinks = logs.service_sinks(service)
+ result = logs.read_logs(sinks, service, sink_id, lines, cursor)
+ except logs.LogError as exc:
+ return _err(rid, exc.code, exc.message)
+ return _ok(rid, result)
+ except Exception as e:
+ logger.exception("service.logs failed")
+ return _err(rid, 5044, str(e))
+
+
+@method("service.logs.follow")
+def _(rid, params: dict) -> dict:
+ """Start or stop following a sink. While following, a daemon thread polls it
+ every second and broadcasts ``service.log`` with the appended lines
+ (coalesced, at most 500 per event); one follower per (service, sink); it
+ stops on ``enabled: false`` or after ten minutes without a client asking
+ again (a final event carries ``stopped``)."""
+ try:
+ from tui_gateway import service_logs as logs
+
+ service = (params or {}).get("service") if isinstance(params, dict) else None
+ if not isinstance(service, str) or not service.strip():
+ return _err(rid, 4029, "service.logs.follow needs a 'service' graph id")
+ service = service.strip()
+ enabled = (params or {}).get("enabled", True)
+ if not isinstance(enabled, bool):
+ return _err(rid, 4001, "enabled must be a boolean")
+ sink_id = (params or {}).get("sink")
+ sink_id = sink_id.strip() if isinstance(sink_id, str) and sink_id.strip() else None
+ try:
+ sinks = logs.service_sinks(service)
+ sink = logs.select_sink(sinks, sink_id, service)
+ if not enabled:
+ stopped = logs.stop_follow(service, sink["id"])
+ return _ok(rid, {"service": service, "following": False, "sink": sink["id"], "stopped": stopped})
+ cursor = logs.parse_cursor((params or {}).get("cursor"))
+ follower = logs.start_follow(sinks, service, sink["id"], _broadcast_global_event, cursor=cursor)
+ except logs.LogError as exc:
+ return _err(rid, exc.code, exc.message)
+ return _ok(rid, {"service": service, "following": True, "sink": follower.sink["id"], "cursor": str(follower.cursor)})
+ except Exception as e:
+ logger.exception("service.logs.follow failed")
+ return _err(rid, 5045, str(e))
+
+
+def register(server) -> None:
+ _registry.install(server)
+
+
+@method("service.deployments")
+def _(rid, params: dict) -> dict:
+ """A manifest's deployments (``service`` is ``arch:<id>`` or the bare id) with
+ their declared probes, log sinks and the last known health and revision —
+ what is known now, without probing. **4030** unknown service, **4001** bad params."""
+ try:
+ from tui_gateway import architecture_store as store
+ from tui_gateway import deployments
+ service_id = store.service_param(params)
+ if service_id is None:
+ return _err(rid, 4029, "service.deployments needs a 'service' id")
+ manifest = store.load_manifest(service_id)
+ if manifest is None:
+ return _err(rid, 4030, f"unknown service: {service_id}")
+ return _ok(rid, {
+ "service": store.graph_id(manifest),
+ "deployments": [
+ deployments.describe_deployment(manifest, d, deployments.last_probe(d["graph_id"]))
+ for d in manifest.get("deployments") or []
+ ],
+ })
+ except Exception as e:
+ logger.exception("service.deployments failed")
+ return _err(rid, 5045, str(e))
+
+
+@method("service.deployments.probe")
+def _(rid, params: dict) -> dict:
+ """Run the declared health and revision probes now for every deployment of a
+ manifest, or for one (``deployment``), and return the results. Probes are the
+ manifest's own declarations (an HTTPS GET or a shell-less command), bounded by
+ their ``timeout_s``. **4030** unknown service, **4050** unknown deployment."""
+ try:
+ from tui_gateway import architecture_store as store
+ from tui_gateway import deployments
+ service_id = store.service_param(params)
+ if service_id is None:
+ return _err(rid, 4029, "service.deployments.probe needs a 'service' id")
+ manifest = store.load_manifest(service_id)
+ if manifest is None:
+ return _err(rid, 4030, f"unknown service: {service_id}")
+ wanted = (params or {}).get("deployment")
+ wanted = wanted.strip() if isinstance(wanted, str) and wanted.strip() else None
+ try:
+ results = deployments.probe_manifest(manifest, deployment_id=wanted, force=True)
+ except deployments.DeploymentError as exc:
+ return _err(rid, exc.code, exc.message)
+ return _ok(rid, {
+ "service": store.graph_id(manifest),
+ "deployments": [
+ deployments.describe_deployment(manifest, d, next((r for r in results if r["deployment"] == d["id"]), None))
+ for d in manifest.get("deployments") or [] if wanted is None or d["id"] == wanted
+ ],
+ })
+ except Exception as e:
+ logger.exception("service.deployments.probe failed")
+ return _err(rid, 5045, str(e))
diff --git hermes-agent/tui_gateway/service_logs.py harness/tui_gateway/service_logs.py
new file mode 100644
index 0000000000000000000000000000000000000000..1f531b1b7d7d6312eb817c69cce9799a8f23febf
--- /dev/null
+++ harness/tui_gateway/service_logs.py
@@ -0,0 +1,591 @@
+"""Service logs: declared and derived sinks, bounded tails, follow — by graph id.
+
+Logs are a property of the RUNNING service, so the RPCs live under ``service.*``
+and take the graph ids the cron dataflow graph uses: ``arch:<id>`` (an
+architecture manifest), ``launchd:<label>``, ``docker:<12>``, ``nomad:<job>``,
+``proc_<id>``. Sinks resolve per provider:
+
+ arch:<id> the manifest's declared sinks; when the manifest binds a launchd
+ runtime, its plist's StandardOutPath/StandardErrorPath are added as
+ ``launchd_stdout``/``launchd_stderr`` unless already declared
+ launchd:<label> the plist's paths as ``stdout``/``stderr``; if a manifest binds
+ that label, its declared sinks are unioned in
+ docker/nomad/proc not implemented yet (4042) — honest, never a fake empty list
+
+Enforcement stays with the architecture manifest: a LOCAL service (a manifest
+with a ``root``) must declare at least one resolvable sink or it is reported
+non-conforming (``architecture_store.conformance_for``). GitHub-only manifests
+are exempt (no runtime here).
+
+Sinks (``logs: [{id, kind, path?, label?}]`` in the manifest):
+
+ file one log file
+ directory a folder of log files; the newest by mtime is the active file
+ launchd_stdout the bound launchd job's ``StandardOutPath`` (path may be omitted)
+ launchd_stderr the bound launchd job's ``StandardErrorPath`` (path may be omitted)
+ command a bounded, shell-less command whose stdout *is* the log tail
+ (``aws logs tail``, ``gcloud logging read``, ``flyctl logs``);
+ declared only on a deployment (``tui_gateway/deployments.py``),
+ read once per request, never followed (4042)
+
+A deployment's graph id (``deploy:<manifest>/<id>``) resolves to that
+deployment's declared sinks.
+Reads are bounded: a tail scans at most ``TAIL_SCAN_BYTES`` from the end and
+returns at most ``MAX_LINES`` lines; a cursor read returns only complete lines
+appended since a byte offset. Following polls a sink from a daemon thread and
+broadcasts ``service.log`` events with the new lines, coalesced, stopping after
+``FOLLOW_IDLE_S`` without a client asking again or when told to stop. Only
+declared or plist-derived paths are ever opened — never a caller-supplied one.
+"""
+from __future__ import annotations
+
+import logging
+import os
+import plistlib
+import threading
+import time
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any, Callable, Dict, List, Optional, Tuple
+
+logger = logging.getLogger(__name__)
+
+SINK_KINDS = ("file", "directory", "launchd_stdout", "launchd_stderr", "command")
+COMMAND_TIMEOUT_S = 30.0
+COMMAND_MAX_BYTES = 4 * 1024 * 1024
+UNSUPPORTED_FOLLOW_PROBLEM = "a command sink is read once per request; following it is not supported"
+LAUNCHD_KINDS = {"launchd_stdout": "StandardOutPath", "launchd_stderr": "StandardErrorPath"}
+DEFAULT_LINES = 200
+MAX_LINES = 2000
+TAIL_SCAN_BYTES = 4 * 1024 * 1024
+MAX_LINE_BYTES = 64 * 1024
+FOLLOW_INTERVAL_S = 1.0
+FOLLOW_IDLE_S = 600.0
+MAX_EVENT_LINES = 500
+NO_CAPTURE_PROBLEM = "no log capture declared: add a logs sink to the manifest"
+EVENT = "service.log"
+UNSUPPORTED_PROVIDER_PROBLEM = "log capture is not implemented for this provider yet"
+
+_LAUNCHD_DIRS: Tuple[str, ...] = ("~/Library/LaunchAgents", "/Library/LaunchAgents", "/Library/LaunchDaemons")
+
+
+class LogError(Exception):
+ def __init__(self, code: int, message: str) -> None:
+ super().__init__(message)
+ self.code = code
+ self.message = message
+
+
+# ── Sink declaration ─────────────────────────────────────────────────────────
+
+
+def launchd_plist_path(label: str, search_dirs: Optional[List[str]] = None) -> Optional[Path]:
+ """The plist that defines a launchd label, or None: the user's agents first,
+ then the system agents and daemons."""
+ for directory in search_dirs if search_dirs is not None else list(_LAUNCHD_DIRS):
+ candidate = Path(directory).expanduser() / f"{label}.plist"
+ if candidate.is_file():
+ return candidate
+ return None
+
+
+def launchd_log_path(label: str, key: str, search_dirs: Optional[List[str]] = None) -> Tuple[Optional[str], Optional[str]]:
+ """``(path, problem)``: the plist's log path for ``key`` (StandardOutPath /
+ StandardErrorPath) or why it could not be derived."""
+ plist = launchd_plist_path(label, search_dirs)
+ if plist is None:
+ return None, f"no launchd plist found for {label!r}"
+ try:
+ with open(plist, "rb") as handle:
+ doc = plistlib.load(handle)
+ except Exception as exc: # malformed plist: report, never raise into the graph
+ return None, f"launchd plist {plist} unreadable: {exc}"
+ value = doc.get(key) if isinstance(doc, dict) else None
+ if not isinstance(value, str) or not value.strip():
+ return None, f"launchd plist {plist.name} declares no {key}"
+ return str(Path(value.strip()).expanduser()), None
+
+
+def normalize_log_sinks(value: Any, runtime: Optional[Dict[str, Any]],
+ launchd_dirs: Optional[List[str]] = None, allow_command: bool = False) -> List[Dict[str, Any]]:
+ """Validate ``logs`` from a manifest. Raises ValueError for a malformed
+ declaration (unknown kind, empty/duplicate id, relative path, launchd kind
+ without a launchd binding). A launchd sink whose plist cannot be read keeps
+ ``path: None`` and a ``problem`` — the manifest stays valid and the service
+ is reported non-conforming rather than disappearing."""
+ if value is None:
+ return []
+ if not isinstance(value, list):
+ raise ValueError("logs must be a list of sinks {id, kind, path?, label?}")
+ sinks: List[Dict[str, Any]] = []
+ seen: set = set()
+ for index, raw in enumerate(value):
+ if not isinstance(raw, dict):
+ raise ValueError(f"logs[{index}] must be an object")
+ sink_id = raw.get("id")
+ if not isinstance(sink_id, str) or not sink_id.strip():
+ raise ValueError(f"logs[{index}].id must be a non-empty string")
+ sink_id = sink_id.strip()
+ if sink_id in seen:
+ raise ValueError(f"logs: duplicate sink id {sink_id!r}")
+ seen.add(sink_id)
+ kind = raw.get("kind")
+ if not isinstance(kind, str) or kind not in SINK_KINDS:
+ raise ValueError(f"logs[{sink_id}].kind must be one of {', '.join(SINK_KINDS)}")
+ label = raw.get("label")
+ if label is not None and not isinstance(label, str):
+ raise ValueError(f"logs[{sink_id}].label must be a string")
+ if kind == "command":
+ if not allow_command:
+ raise ValueError(f"logs[{sink_id}]: kind command is only valid on a deployment's logs")
+ argv = raw.get("argv")
+ if isinstance(argv, str):
+ import shlex
+ argv = shlex.split(argv)
+ if not isinstance(argv, list) or not argv or not all(isinstance(part, str) and part.strip() for part in argv):
+ raise ValueError(f"logs[{sink_id}].argv must be a non-empty list of strings")
+ sinks.append({"id": sink_id, "kind": kind, "label": (label or sink_id).strip(), "path": None, "argv": [part.strip() for part in argv]})
+ continue
+ path = raw.get("path")
+ problem: Optional[str] = None
+ if path is not None:
+ if not isinstance(path, str) or not path.strip():
+ raise ValueError(f"logs[{sink_id}].path must be a non-empty string when present")
+ path = str(Path(path.strip()).expanduser())
+ if not os.path.isabs(path):
+ raise ValueError(f"logs[{sink_id}].path must be absolute (got {raw.get('path')!r})")
+ if kind in LAUNCHD_KINDS:
+ if not runtime or runtime.get("provider") != "launchd":
+ raise ValueError(f"logs[{sink_id}]: kind {kind} needs a runtime binding with provider launchd")
+ if path is None:
+ path, problem = launchd_log_path(str(runtime["id"]), LAUNCHD_KINDS[kind], launchd_dirs)
+ elif path is None:
+ raise ValueError(f"logs[{sink_id}]: kind {kind} needs a path")
+ sink: Dict[str, Any] = {"id": sink_id, "kind": kind, "label": (label or sink_id).strip(), "path": path}
+ if problem:
+ sink["problem"] = problem
+ sinks.append(sink)
+ return sinks
+
+
+def capture_problem(manifest: Dict[str, Any]) -> Optional[str]:
+ """Why a LOCAL manifest fails log-capture enforcement, or None when it passes:
+ at least one declared sink must resolve to a path. GitHub-only manifests
+ are exempt (logs are a runtime property, and the runtime is not here)."""
+ if not manifest.get("root"):
+ return None
+ sinks = manifest.get("logs") or []
+ if not sinks:
+ return NO_CAPTURE_PROBLEM
+ if not any(sink.get("path") or sink.get("argv") for sink in sinks):
+ problems = "; ".join(str(sink.get("problem") or f"{sink['id']}: no path") for sink in sinks)
+ return f"no log sink resolves: {problems}"
+ return None
+
+
+# ── Sink resolution ──────────────────────────────────────────────────────────
+
+
+def _iso(timestamp: float) -> str:
+ return datetime.fromtimestamp(timestamp, timezone.utc).isoformat().replace("+00:00", "Z")
+
+
+def active_file(sink: Dict[str, Any]) -> Optional[Path]:
+ """The file a sink reads: the declared file, or the newest regular file in a
+ directory sink (by mtime, then name for determinism). None when unresolved."""
+ path = sink.get("path")
+ if not path:
+ return None
+ target = Path(path)
+ if sink.get("kind") != "directory":
+ return target
+ if not target.is_dir():
+ return None
+ candidates = [p for p in target.iterdir() if p.is_file() and not p.name.startswith(".")]
+ if not candidates:
+ return None
+ candidates.sort(key=lambda p: (p.stat().st_mtime, p.name))
+ return candidates[-1]
+
+
+def resolve_sink(sink: Dict[str, Any]) -> Dict[str, Any]:
+ """The sink as clients see it: declaration plus whether the active file
+ exists, its size and mtime. Fail-open per sink: a missing file is
+ ``exists: false``, never an error."""
+ resolved = {"id": sink["id"], "kind": sink["kind"], "label": sink.get("label") or sink["id"],
+ "path": sink.get("path"), "exists": False, "size_bytes": 0, "modified_at": None}
+ if sink.get("problem"):
+ resolved["problem"] = sink["problem"]
+ if sink.get("kind") == "command":
+ import shutil
+ argv = list(sink.get("argv") or [])
+ resolved["argv"] = argv
+ resolved["exists"] = bool(argv) and shutil.which(argv[0]) is not None
+ if argv and not resolved["exists"]:
+ resolved["problem"] = f"command not found: {argv[0]}"
+ return resolved
+ try:
+ target = active_file(sink)
+ if target is not None and target.is_file():
+ stat = target.stat()
+ resolved.update({"path": str(target), "exists": True, "size_bytes": int(stat.st_size), "modified_at": _iso(stat.st_mtime)})
+ elif sink.get("kind") == "directory" and sink.get("path") and Path(sink["path"]).is_dir():
+ resolved["problem"] = "directory has no log files yet"
+ except OSError as exc:
+ resolved["problem"] = f"{type(exc).__name__}: {exc}"
+ return resolved
+
+
+def resolve_sinks(manifest: Dict[str, Any]) -> List[Dict[str, Any]]:
+ return [resolve_sink(sink) for sink in manifest.get("logs") or []]
+
+
+def select_sink(sinks: List[Dict[str, Any]], sink_id: Optional[str], service: str) -> Dict[str, Any]:
+ """The sink to read: by id, or the first one. Raises LogError 4040 when the
+ id is unknown or the service has no sinks at all."""
+ if not sinks:
+ raise LogError(4040, f"{service}: {NO_CAPTURE_PROBLEM}")
+ if sink_id is None:
+ return sinks[0]
+ for sink in sinks:
+ if sink["id"] == sink_id:
+ return sink
+ raise LogError(4040, f"unknown log sink {sink_id!r}; declared: {', '.join(s['id'] for s in sinks)}")
+
+
+# ── Resolution by graph id ───────────────────────────────────────────────────
+
+
+def launchd_sinks(label: str, launchd_dirs: Optional[List[str]] = None,
+ ids: Tuple[str, str] = ("stdout", "stderr")) -> List[Dict[str, Any]]:
+ """The sinks a launchd label's plist names (StandardOutPath → ids[0],
+ StandardErrorPath → ids[1]). Only paths the plist actually declares."""
+ sinks: List[Dict[str, Any]] = []
+ for sink_id, (kind, key) in zip(ids, LAUNCHD_KINDS.items()):
+ path, _problem = launchd_log_path(label, key, launchd_dirs)
+ if path:
+ sinks.append({"id": sink_id, "kind": kind, "label": f"launchd {key}", "path": path})
+ return sinks
+
+
+def _union(primary: List[Dict[str, Any]], extra: List[Dict[str, Any]]) -> List[Dict[str, Any]]:
+ """``primary`` plus every ``extra`` sink whose id and (kind, path) are new."""
+ seen_ids = {s["id"] for s in primary}
+ seen_paths = {(s["kind"], s.get("path")) for s in primary}
+ merged = list(primary)
+ for sink in extra:
+ if sink["id"] in seen_ids or (sink["kind"], sink.get("path")) in seen_paths:
+ continue
+ merged.append(sink)
+ seen_ids.add(sink["id"])
+ seen_paths.add((sink["kind"], sink.get("path")))
+ return merged
+
+
+def service_sinks(graph_id: str, home: Optional[str] = None, launchd_dirs: Optional[List[str]] = None) -> List[Dict[str, Any]]:
+ """Every sink a graph service id resolves to, per provider (see module doc).
+ LogError 4030 for an unknown ``arch:`` service, 4042 for a provider without
+ log capture, 4001 for an id that is not a graph service id."""
+ from tui_gateway import architecture_store as store
+ from tui_gateway import deployments
+ parsed = deployments.parse_graph_id(graph_id)
+ if parsed is not None:
+ manifest_id, dep_id = parsed
+ manifest = store.load_manifest(manifest_id, home)
+ if manifest is None:
+ raise LogError(4030, f"unknown service: {store.ID_PREFIX}{manifest_id}")
+ deployment = deployments.find_deployment(manifest, dep_id)
+ if deployment is None:
+ raise LogError(4050, f"{manifest_id} has no deployment {dep_id!r}")
+ return list(deployment.get("logs") or [])
+ if graph_id.startswith(store.ID_PREFIX):
+ manifest = store.load_manifest(graph_id, home)
+ if manifest is None:
+ raise LogError(4030, f"unknown service: {graph_id}")
+ sinks = list(manifest.get("logs") or [])
+ runtime = manifest.get("runtime") or {}
+ if runtime.get("provider") == "launchd":
+ sinks = _union(sinks, launchd_sinks(str(runtime["id"]), launchd_dirs, ids=("launchd_stdout", "launchd_stderr")))
+ return sinks
+ if graph_id.startswith("launchd:"):
+ label = graph_id[len("launchd:"):]
+ if not label:
+ raise LogError(4001, "launchd service id needs a label")
+ sinks = launchd_sinks(label, launchd_dirs)
+ for manifest in store.list_manifests(home):
+ runtime = manifest.get("runtime") or {}
+ if runtime.get("graph_id") == graph_id:
+ sinks = _union(sinks, list(manifest.get("logs") or []))
+ return sinks
+ if graph_id.startswith(("docker:", "nomad:", "proc_")):
+ raise LogError(4042, f"{graph_id}: {UNSUPPORTED_PROVIDER_PROBLEM}")
+ raise LogError(4001, f"{graph_id!r} is not a graph service id (arch:, deploy:, launchd:, docker:, nomad:, proc_)")
+# ── Bounded reads ────────────────────────────────────────────────────────────
+
+
+def _decode(chunk: bytes) -> str:
+ return chunk.decode("utf-8", errors="replace")
+
+
+def _split_lines(data: bytes) -> List[str]:
+ return [_decode(line[:MAX_LINE_BYTES]) for line in data.split(b"\n")]
+
+
+def read_tail(path: Path, lines: int) -> Dict[str, Any]:
+ """The last ``lines`` complete lines of ``path`` (scanning at most
+ TAIL_SCAN_BYTES from the end) and the cursor to continue from: the file's
+ byte length, so the next read sees only what is appended afterwards."""
+ with open(path, "rb") as handle:
+ handle.seek(0, os.SEEK_END)
+ size = handle.tell()
+ start = max(0, size - TAIL_SCAN_BYTES)
+ handle.seek(start)
+ data = handle.read(size - start)
+ # A partial trailing line (no newline yet) is not returned; it is re-read
+ # once complete via the cursor, which stays at the end of the last full line.
+ complete_end = data.rfind(b"\n")
+ if complete_end == -1:
+ return {"lines": [], "cursor": str(start), "truncated": False, "scanned_from": start}
+ body = data[:complete_end]
+ all_lines = _split_lines(body)
+ if start > 0 and all_lines:
+ all_lines = all_lines[1:] # the first piece is the tail of a line we did not fully scan
+ truncated = len(all_lines) > lines or start > 0
+ return {"lines": all_lines[-lines:], "cursor": str(start + complete_end + 1), "truncated": truncated, "scanned_from": start}
+
+
+def read_since(path: Path, cursor: int, lines: int) -> Dict[str, Any]:
+ """Every complete line appended after byte ``cursor`` (bounded by ``lines``,
+ ``truncated`` when more remain). A file shorter than the cursor was rotated
+ or truncated: restart from the tail and say so."""
+ size = path.stat().st_size
+ if size < cursor:
+ result = read_tail(path, lines)
+ result["rotated"] = True
+ return result
+ if size == cursor:
+ return {"lines": [], "cursor": str(cursor), "truncated": False}
+ budget = min(size - cursor, TAIL_SCAN_BYTES)
+ with open(path, "rb") as handle:
+ handle.seek(cursor)
+ data = handle.read(budget)
+ complete_end = data.rfind(b"\n")
+ if complete_end == -1:
+ return {"lines": [], "cursor": str(cursor), "truncated": False}
+ body = data[:complete_end]
+ all_lines = _split_lines(body)
+ if len(all_lines) > lines:
+ kept = all_lines[:lines]
+ consumed = sum(len(line.encode("utf-8")) + 1 for line in kept)
+ # Recompute from bytes to stay exact for lines that decoded with replacements.
+ consumed = len(b"\n".join(body.split(b"\n")[:lines])) + 1
+ return {"lines": kept, "cursor": str(cursor + consumed), "truncated": True}
+ return {"lines": all_lines, "cursor": str(cursor + complete_end + 1), "truncated": (size - cursor) > budget}
+
+
+def parse_lines(value: Any) -> int:
+ if value is None:
+ return DEFAULT_LINES
+ if isinstance(value, bool) or not isinstance(value, int):
+ raise LogError(4001, "lines must be an integer")
+ if value < 1 or value > MAX_LINES:
+ raise LogError(4001, f"lines must be between 1 and {MAX_LINES}")
+ return value
+
+
+def parse_cursor(value: Any) -> Optional[int]:
+ if value is None or value == "":
+ return None
+ if isinstance(value, bool) or not isinstance(value, (str, int)):
+ raise LogError(4001, "cursor must be the string returned by a previous read")
+ try:
+ cursor = int(value)
+ except ValueError as exc:
+ raise LogError(4001, "cursor must be the string returned by a previous read") from exc
+ if cursor < 0:
+ raise LogError(4001, "cursor must not be negative")
+ return cursor
+
+
+def read_logs(sinks: List[Dict[str, Any]], service: str, sink_id: Optional[str], lines: int, cursor: Optional[int]) -> Dict[str, Any]:
+ """``service.logs``: a bounded tail or the lines since a cursor, from one of
+ the service's sinks only. LogError 4040 unknown sink, 4041 sink not present."""
+ sink = select_sink(sinks, sink_id, service)
+ if sink.get("kind") == "command":
+ result = read_command(sink, lines)
+ result.update({"service": service, "sink": resolve_sink(sink), "sinks": [resolve_sink(s) for s in sinks], "encoding": "utf-8-replace"})
+ return result
+ target = active_file(sink)
+ if target is None or not target.is_file():
+ raise LogError(4041, f"log sink {sink['id']!r} has no file yet" + (f" ({sink['problem']})" if sink.get("problem") else ""))
+ try:
+ result = read_tail(target, lines) if cursor is None else read_since(target, cursor, lines)
+ except OSError as exc:
+ raise LogError(4041, f"log sink {sink['id']!r} unreadable: {exc}") from exc
+ result.pop("scanned_from", None)
+ resolved = resolve_sink(sink)
+ resolved["path"] = str(target)
+ result.update({"service": service, "sink": resolved, "sinks": [resolve_sink(s) for s in sinks], "encoding": "utf-8-replace"})
+ return result
+
+
+def read_command(sink: Dict[str, Any], lines: int,
+ runner: Optional[Callable[[List[str], float], Any]] = None) -> Dict[str, Any]:
+ """Run a command sink once, bounded in time and bytes, and return the last
+ ``lines`` lines of its stdout. There is no cursor: the command is the tail.
+ LogError 4041 when the executable is missing, times out or fails."""
+ import shutil
+ import subprocess
+ argv = list(sink.get("argv") or [])
+ if not argv:
+ raise LogError(4041, f"log sink {sink['id']!r} declares no command")
+ if shutil.which(argv[0]) is None:
+ raise LogError(4041, f"log sink {sink['id']!r}: command not found: {argv[0]}")
+ try:
+ if runner is not None:
+ completed = runner(argv, COMMAND_TIMEOUT_S)
+ else:
+ completed = subprocess.run(argv, capture_output=True, timeout=COMMAND_TIMEOUT_S, check=False, stdin=subprocess.DEVNULL) # noqa: S603 - declared argv only
+ except subprocess.TimeoutExpired as exc:
+ raise LogError(4041, f"log sink {sink['id']!r}: command timed out after {COMMAND_TIMEOUT_S:g}s") from exc
+ except OSError as exc:
+ raise LogError(4041, f"log sink {sink['id']!r}: {exc}") from exc
+ stdout = completed.stdout if isinstance(completed.stdout, (bytes, bytearray)) else str(completed.stdout or "").encode("utf-8")
+ stderr = completed.stderr if isinstance(completed.stderr, (bytes, bytearray)) else str(completed.stderr or "").encode("utf-8")
+ if completed.returncode != 0 and not stdout.strip():
+ detail = _decode(bytes(stderr)[-2000:]).strip().splitlines()
+ raise LogError(4041, f"log sink {sink['id']!r}: command exited {completed.returncode}" + (f": {detail[-1][:200]}" if detail else ""))
+ data = bytes(stdout)[-COMMAND_MAX_BYTES:]
+ all_lines = [line for line in _split_lines(data) if line != ""]
+ tail = all_lines[-lines:] if lines > 0 else []
+ return {"lines": tail, "cursor": None, "truncated": len(all_lines) > len(tail) or len(stdout) > COMMAND_MAX_BYTES,
+ "exit_code": int(completed.returncode)}
+
+
+# ── Follow ───────────────────────────────────────────────────────────────────
+class Follower:
+ """One followed sink: polls for appended lines and broadcasts them."""
+
+ def __init__(self, service: str, sink: Dict[str, Any], cursor: int, broadcast: Callable[[str, Dict[str, Any]], None],
+ clock: Callable[[], float] = time.monotonic) -> None:
+ self.service = service
+ self.sink = sink
+ self.cursor = cursor
+ self.broadcast = broadcast
+ self.clock = clock
+ self.started_at = clock()
+ self.last_activity = self.started_at
+ self.stop_requested = threading.Event()
+ self.thread: Optional[threading.Thread] = None
+
+ @property
+ def key(self) -> Tuple[str, str]:
+ return (self.service, self.sink["id"])
+
+ def touch(self) -> None:
+ """A client asked again: the idle clock restarts."""
+ self.last_activity = self.clock()
+
+ def idle_for(self) -> float:
+ return self.clock() - self.last_activity
+
+ def poll_once(self) -> Optional[Dict[str, Any]]:
+ """Read what was appended since the cursor; broadcast and return the
+ payload when there are new lines, else None. Never raises."""
+ target = active_file(self.sink)
+ if target is None or not target.is_file():
+ return None
+ try:
+ result = read_since(target, self.cursor, MAX_EVENT_LINES)
+ except OSError:
+ logger.debug("log follow read failed for %s", self.key, exc_info=True)
+ return None
+ self.cursor = int(result["cursor"])
+ if not result["lines"] and not result.get("rotated"):
+ return None
+ payload: Dict[str, Any] = {"service": self.service, "sink": self.sink["id"], "lines": result["lines"], "cursor": result["cursor"]}
+ if result.get("rotated"):
+ payload["rotated"] = True
+ self.broadcast(EVENT, payload)
+ return payload
+
+ def stop(self, reason: str) -> None:
+ if self.stop_requested.is_set():
+ return
+ self.stop_requested.set()
+ self.broadcast(EVENT, {"service": self.service, "sink": self.sink["id"], "lines": [], "cursor": str(self.cursor), "stopped": reason})
+
+ def run(self, interval: float = FOLLOW_INTERVAL_S, sleep: Callable[[float], None] = time.sleep) -> None:
+ """The polling loop: until stopped or idle for FOLLOW_IDLE_S."""
+ while not self.stop_requested.is_set():
+ if self.idle_for() >= FOLLOW_IDLE_S:
+ _forget(self)
+ self.stop("idle-timeout")
+ return
+ try:
+ self.poll_once()
+ except Exception: # pragma: no cover - poll_once already guards
+ logger.debug("log follow poll failed for %s", self.key, exc_info=True)
+ sleep(interval)
+
+
+_followers: Dict[Tuple[str, str], Follower] = {}
+_followers_lock = threading.Lock()
+
+
+def _forget(follower: Follower) -> None:
+ with _followers_lock:
+ if _followers.get(follower.key) is follower:
+ del _followers[follower.key]
+
+
+def start_follow(sinks: List[Dict[str, Any]], service: str, sink_id: Optional[str],
+ broadcast: Callable[[str, Dict[str, Any]], None], cursor: Optional[int] = None,
+ spawn: bool = True, clock: Callable[[], float] = time.monotonic) -> Follower:
+ """Follow one of the service's sinks from its current end (or ``cursor``).
+ One follower per (service, sink): asking again refreshes the idle clock and
+ returns the existing follower. ``spawn=False`` creates without a thread
+ (tests drive ``poll_once`` themselves)."""
+ sink = select_sink(sinks, sink_id, service)
+ if sink.get("kind") == "command":
+ raise LogError(4042, f"log sink {sink['id']!r}: {UNSUPPORTED_FOLLOW_PROBLEM}")
+ target = active_file(sink)
+ if target is None or not target.is_file():
+ raise LogError(4041, f"log sink {sink['id']!r} has no file yet; nothing to follow")
+ with _followers_lock:
+ existing = _followers.get((service, sink["id"]))
+ if existing is not None and not existing.stop_requested.is_set():
+ existing.touch()
+ return existing
+ start_cursor = cursor if cursor is not None else target.stat().st_size
+ follower = Follower(service, sink, start_cursor, broadcast, clock)
+ _followers[follower.key] = follower
+ if spawn:
+ thread = threading.Thread(target=follower.run, name=f"arch-logs:{service}:{sink['id']}", daemon=True)
+ follower.thread = thread
+ thread.start()
+ return follower
+
+
+def stop_follow(service: str, sink_id: str) -> bool:
+ """Stop following; True when a follower existed."""
+ with _followers_lock:
+ follower = _followers.pop((service, sink_id), None)
+ if follower is None:
+ return False
+ follower.stop("stopped")
+ return True
+
+
+def following(service: str, sink_id: str) -> Optional[Follower]:
+ with _followers_lock:
+ follower = _followers.get((service, sink_id))
+ return follower if follower is not None and not follower.stop_requested.is_set() else None
+
+
+def stop_all(reason: str = "shutdown") -> None:
+ with _followers_lock:
+ active = list(_followers.values())
+ _followers.clear()
+ for follower in active:
+ follower.stop(reason)