{"$schema":"https://json-schema.org/draft/2020-12/schema","$id":"https://docs.aiagentnet.cloud/ahcp/v1/schema/ahcp.surface.schema.json","title":"AHCP Adaptation Surface Package","description":"Machine-readable adaptation package for AHCP Protocol 1.0. A conformant Full package declares every human-reachable feature of the software object, maps each to commands, and provides parity tasks with verifiable expect predicates.","type":"object","additionalProperties":false,"required":["ahcp_version","badge","software","vendor","features","uncovered_features","commands","parity_tasks","conformance"],"properties":{"ahcp_version":{"type":"string","pattern":"^[0-9]+\\.[0-9]+\\.[0-9]+$","description":"AHCP protocol version claimed by this package (e.g. 1.0.0)."},"badge":{"type":"string","enum":["full","partial","experimental"]},"software":{"type":"object","additionalProperties":false,"required":["name","title","version","description"],"properties":{"name":{"type":"string","minLength":1,"description":"Stable software object id (reverse-DNS recommended)."},"title":{"type":"string","minLength":1},"version":{"type":"string","minLength":1},"description":{"type":"string","minLength":1},"product_class":{"type":"string"},"platforms":{"type":"array","items":{"type":"string"}},"equivalents":{"type":"array","items":{"type":"string"}},"notes":{"type":"array","items":{"type":"string"}},"runtime_notes":{"type":"array","items":{"type":"string"}}}},"vendor":{"type":"object","additionalProperties":false,"required":["name"],"properties":{"name":{"type":"string"},"contact":{"type":"string"},"upstream":{"type":"string"}}},"features":{"type":"array","minItems":1,"items":{"$ref":"#/$defs/feature"}},"uncovered_features":{"type":"array","description":"MUST be empty when badge=full.","items":{"type":"object","additionalProperties":false,"required":["feature_id","title","reason"],"properties":{"feature_id":{"type":"string"},"title":{"type":"string"},"reason":{"type":"string"},"commands":{"type":"array","items":{"type":"string"}}}}},"commands":{"type":"array","minItems":1,"items":{"$ref":"#/$defs/command"}},"parity_tasks":{"type":"array","minItems":1,"items":{"$ref":"#/$defs/parity_task"}},"coverage":{"type":"object","additionalProperties":true},"conformance":{"$ref":"#/$defs/conformance"},"sample_meta":{"type":"object","additionalProperties":true},"error_catalog_ref":{"type":"string","description":"URI of AHCP error code catalog this package uses.","default":"https://docs.aiagentnet.cloud/ahcp/v1/errors.json"},"bindings":{"type":"array","description":"How this host exposes commands (builtin, MCP, HTTP).","items":{"$ref":"#/$defs/binding"}}},"allOf":[{"if":{"properties":{"badge":{"const":"full"}}},"then":{"properties":{"uncovered_features":{"maxItems":0}}}}],"$defs":{"feature":{"type":"object","additionalProperties":false,"required":["feature_id","title","description","human_path","commands","side_effects","sensitivity"],"properties":{"feature_id":{"type":"string","pattern":"^[a-z][a-z0-9_.-]*$"},"title":{"type":"string"},"description":{"type":"string"},"human_path":{"type":"string","description":"How a human performs this feature with keyboard/mouse/UI."},"commands":{"type":"array","minItems":1,"items":{"type":"string"}},"side_effects":{"type":"array","items":{"type":"string","enum":["read","write_fs","read_fs","network","navigation","session","dom_mutation","possible_navigation","possible_exfiltration","write_profile","read_secret","write_secret","ui","none"]}},"sensitivity":{"type":"string","enum":["low","operator","approval"]}}},"command":{"type":"object","additionalProperties":false,"required":["id","implementation","transport","runtime","input_schema","output_schema","errors"],"properties":{"id":{"type":"string","pattern":"^[a-z][a-z0-9_.-]*$"},"implementation":{"type":"string","enum":["native","cli","http","mcp","plugin","ui-drive","other"]},"transport":{"type":"string","description":"Host transport id, e.g. agentos-x-builtin-tool, mcp.server-name, http.v1"},"runtime":{"type":"string","enum":["shipped","specified"]},"input_schema":{"type":"object","description":"JSON Schema for command arguments."},"output_schema":{"type":"object","description":"JSON Schema for successful command output."},"errors":{"type":"array","items":{"oneOf":[{"type":"string"},{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"retryable":{"type":"boolean"}}}]}},"notes":{"type":"array","items":{"type":"string"}}}},"parity_task":{"type":"object","additionalProperties":false,"required":["id","feature_ids","title","human_steps","agent_commands","expect"],"properties":{"id":{"type":"string"},"feature_ids":{"type":"array","minItems":1,"items":{"type":"string"}},"title":{"type":"string"},"human_steps":{"type":"array","minItems":1,"items":{"type":"string"}},"agent_commands":{"type":"array","minItems":1,"items":{"type":"object","required":["id"],"properties":{"id":{"type":"string"},"args":{"type":"object"}}}},"expect":{"type":"object","description":"Machine-checkable predicates (see AHCP expect vocabulary)."},"runtime":{"type":"string","enum":["shipped","specified"]},"notes":{"type":"array","items":{"type":"string"}}}},"conformance":{"type":"object","additionalProperties":false,"required":["status","feature_count","command_count","parity_task_count","parity_feature_coverage","dispatch_aligned","schema_validated"],"properties":{"status":{"type":"string","enum":["conformant_full","conformant_partial","experimental","nonconformant"]},"feature_count":{"type":"integer","minimum":0},"command_count":{"type":"integer","minimum":0},"parity_task_count":{"type":"integer","minimum":0},"parity_feature_coverage":{"type":"number","minimum":0,"maximum":1,"description":"Fraction of features referenced by at least one parity task."},"dispatch_aligned":{"type":"boolean","description":"Every command id is registered in host dispatch."},"schema_validated":{"type":"boolean","description":"Package validates against this JSON Schema."},"harness_last_run":{"type":"string","format":"date-time"},"harness_results_uri":{"type":"string"},"notes":{"type":"array","items":{"type":"string"}}}},"binding":{"type":"object","additionalProperties":false,"required":["kind","id"],"properties":{"kind":{"type":"string","enum":["builtin","mcp","http","cli"]},"id":{"type":"string"},"endpoint":{"type":"string"},"notes":{"type":"string"}}}}}