# Conversational & Self-Healing Surface Specification
# This file codifies the Possibility conversational + self-healing contract as a
# first-class .kno spec — a cross-cutting integration profile that ties together
# the canonical error envelopes (REST RFC 9457, MCP, A2A), the discoverability
# contract, and the Self-Healing Maturity Rubric under a single discoverable,
# versioned surface.
#
# Version: 0.1.1
# Status: Draft
# Last Updated: 2026-05-21
#
# THREE-GATE TEST (per kno-foundational-principles.md § 0.6):
#   Gate 1 (Distinctness): Conversational + self-healing is a cross-cutting
#     integration profile — fundamentally different from api-spec (which
#     documents API endpoints), document-schema (which documents entity
#     shape), or error-envelope-spec.md (which is the REST-surface artifact
#     of the contract). The conversational-surface profile is the umbrella
#     that ties those siblings together into a single contract every public
#     API surface conforms to. Compare to `otel-spec.kno`, which plays the
#     equivalent umbrella role for observability across services.
#   Gate 2 (Reusability): Referenced by every API in `content/apis/*.kno`
#     (59 files at audit time), by all three envelope shapes
#     (REST/MCP/A2A), by the discoverability lint
#     (scripts/lint-discoverability-contract.ts), by the self-healing
#     scorer (#1749), and by every per-API remediation sweep in P4
#     (#1762/1763/1764). Single source of truth for the M45 Phase 2
#     contract; Phase 3 plumbing (#1756-1761) and Phase 4 sweeps consume
#     it directly.
#   Gate 3 (Clarity): Without this spec, the contract is scattered across
#     `error-envelope-spec.md` (REST), `kno-tool-transformer.ts` (MCP),
#     `a2a/error-envelope.ts` (A2A), `api-spec.kno` v0.6.0 (parameter-level
#     discoverability), `self-healing-maturity-rubric.md` (the yardstick),
#     and `lint-discoverability-contract.ts` (the enforcement). A single
#     versioned umbrella anchors the contract to one navigable artifact
#     and makes the bedrock conformance explicit.
#
# EMBRACE-AND-EXTEND:
#   - REST: RFC 9457 Problem Details for HTTP APIs (https://www.rfc-editor.org/rfc/rfc9457)
#   - MCP: Model Context Protocol tool error semantics
#     (https://modelcontextprotocol.io/specification/server/tools#error-handling)
#   - A2A: A2A JSON-RPC 2.0 error response shape
#     (https://google.github.io/A2A/#/documentation?id=jsonrpc-error-codes)
#   Possibility extensions live in named `pspace.*` envelope keys and SHOULD
#   degrade gracefully — partners ignoring extensions still receive the
#   standard envelope.
#
# KEY RELATIONSHIPS:
#   - Operationalizes the M45 Self-Healing Maturity Rubric (5 dimensions × 0-4
#     scale) at the per-API-manifest level.
#   - Discoverability contract (#1754) makes Dimension 1 ("Discoverability of
#     choices") machine-checkable at the .kno layer.
#   - Error envelope shapes (#1751/1752/1753) operationalize Dimensions 2
#     ("Error clarity") and 3 ("Remediation guidance") across the three
#     agent-consumed surfaces.
#   - Per-API remediation sweeps in P4 (#1762/1763/1764) bring each manifest
#     up to the rubric thresholds defined here.
#   - Bidirectional bedrock conformance audit completed during authoring;
#     audit report at `docs/audits/conformance-surface-spec/2026-05-19/`.

# =============================================================================
# @kno:manifest
# =============================================================================
$schema: kno@0.0.9
id: 01KS13QXWZF99YFC5VR2ZX3M6P
slug: conversational-surface-spec
type: spec
version: 0.1.1

# =============================================================================
# VISIBILITY DECLARATION (REQ-18) — collection default
# =============================================================================
# Conversational-surface spec is public reference knowledge — every integrator
# (browser, MCP client, A2A peer) needs to consume the contract this defines.
# Per REQ-18, individual entities MAY override. Drives the four-surface
# contract per kno-system_architecture.md § Agent Surface Integration.
visibility: public

title: "Conversational & Self-Healing Surface Specification"
purpose: |
  Codify the conversational + self-healing contract that every Possibility
  API surface (REST, MCP, A2A) MUST satisfy. Operationalizes Milestone 45
  (Conversational & Self-Healing Surfaces v1) at the .kno layer — a single
  versioned umbrella over the three envelope shapes, the discoverability
  contract, and the maturity rubric.

  **What this IS:** A cross-cutting integration profile. The single source
  of truth for "what does it mean for a Possibility API to be
  conversational and self-healing?" — and the discoverable anchor every
  manifest sweep, scorer run, and partner integration should resolve to.

  **What this is NOT:** A new entity-type schema. No `.kno` files declare
  `$schema: conversational-surface@0.1.1`. The contract is consumed
  through:
    - REST: `Content-Type: application/problem+json` envelope on every
      4xx/5xx (canonical at `docs/architecture/error-envelope-spec.md`).
    - MCP: `CallToolResult` with `isError: true` + structured
      `pspace.mcp.error.v1` envelope (canonical at
      `services/pspace-api/src/mcp/error-envelope.ts`).
    - A2A: JSON-RPC error response with `pspace.a2a.error.v1` envelope in
      `error.data` (canonical at
      `services/pspace-api/src/a2a/error-envelope.ts`).
    - Discoverability: `parameters[].enum` / `oneOf` / `choices_endpoint`
      on every constrained-choice param in `content/apis/*.kno` (canonical
      at `specs/api-spec.kno` v0.6.0).

  **Five-dimension yardstick.** Each API manifest is scored 0–4 on every
  dimension; the rubric is the yardstick, this spec is the contract:

  | Dim | Name                       | What it answers                                     |
  | --- | -------------------------- | --------------------------------------------------- |
  | D1  | Discoverability of choices | Can a caller find valid inputs without trial+error? |
  | D2  | Error clarity              | Is the failure mode structured and parseable?       |
  | D3  | Remediation guidance       | Does the response point to the next safe action?    |
  | D4  | Auto-fix capability        | Can the platform perform the corrective action?     |
  | D5  | Cross-surface parity       | Do REST/MCP/A2A say the same thing the same way?    |

  See `docs/architecture/self-healing-maturity-rubric.md` for the score
  anchors and per-dimension evidence requirements.

# =============================================================================
# @kno:taxonomy
# =============================================================================
taxonomy:
  topics:
    - api-contract
    - error-envelope
    - self-healing
    - discoverability
    - cross-surface-parity
    - remediation
  keywords:
    - rfc-9457
    - problem-details
    - conversational-surface
    - self-healing
    - discoverability-contract
    - error-envelope
    - remediation
    - valid-values
    - choices_endpoint
    - maturity-rubric

# =============================================================================
# @kno:provenance
# =============================================================================
provenance:
  origin:
    id: 01KS13QXWZF99YFC5VR2ZX3M6P
    timestamp: "2026-05-19T20:30:00Z"
    tool: manual
    issue: 1755
    milestone: 45
    phase: P2

# =============================================================================
# @kno:relationships
# =============================================================================
relationships:
  extends:
    - url: "https://www.rfc-editor.org/rfc/rfc9457"
      reason: "RFC 9457 Problem Details for HTTP APIs — REST envelope canonical reference (embrace-and-extend)"
    - url: "https://modelcontextprotocol.io/specification/server/tools#error-handling"
      reason: "MCP tool error semantics — MCP envelope reference (embrace-and-extend)"
    - url: "https://google.github.io/A2A/#/documentation?id=jsonrpc-error-codes"
      reason: "A2A JSON-RPC 2.0 error response shape — A2A envelope reference (embrace-and-extend)"

  depends_on:
    - xri: "kno://specs/kno-spec"
      reason: "Conforms to KNO format specification"
    - xri: "kno://specs/api-spec"
      reason: "Discoverability contract (#1754) declared on parameters[].enum / oneOf / choices_endpoint in api-spec.kno v0.6.0"

  enables:
    - xri: "kno://docs/architecture/self-healing-maturity-rubric"
      reason: "Rubric scores manifest conformance against this contract"
    - xri: "kno://scripts/lint-discoverability-contract"
      reason: "Lint enforces D1 (Discoverability) at pre-commit time"

  related_to:
    - xri: "kno://docs/architecture/error-envelope-spec"
      reason: "REST surface artifact of the same contract (RFC 9457 + Possibility extensions)"
    - xri: "kno://services/pspace-api/mcp/error-envelope"
      reason: "MCP surface implementation of the same contract"
    - xri: "kno://services/pspace-api/a2a/error-envelope"
      reason: "A2A surface implementation of the same contract"
    - xri: "kno://content/knowledge-base/remediation-block-pattern"
      reason: "Source-of-truth for the discriminated `remediation.type` taxonomy this spec references"

# =============================================================================
# @kno:quality
# =============================================================================
quality:
  completeness: 0.85
  last_reviewed: "2026-05-21"
  review_status: draft
  reviewed_by: "claude"
  notes: |
    Authored 2026-05-19 alongside M45.P2 #1755. Status remains Draft until
    Phase 3 plumbing (#1756-#1761) lands — the spec describes a contract
    that exists at the manifest layer (substrate via api-spec.kno v0.6.0,
    enforcement via the discoverability lint, projection via the
    transformer) but the platform-wide plumbing that emits the envelopes
    automatically is Phase 3 work. Draft → Stable transition is gated by
    Phase 3 completion and an end-of-epic code-auditor pass per
    `code-auditor` skill conventions.

# =============================================================================
# @kno:history
# =============================================================================
_history:
  version: 1
  created: "2026-05-19T20:30:00Z"
  created_by: "claude"
  changelog:
    - version: "0.1.1"
      date: "2026-05-21"
      summary: "Clarify that Phase 4 threshold applies to every applicable rubric dimension; N/A dimensions satisfy the threshold by construction. No envelope or schema-shape change."
    - version: "0.1.0"
      date: "2026-05-19"
      summary: "Initial draft (M45.P2 #1755). Codifies the conversational + self-healing contract as a cross-cutting integration profile. References all three envelope shapes (#1751/1752/1753), the discoverability contract (#1754), and the Self-Healing Maturity Rubric. Bidirectional bedrock conformance audit completed (no CONFORMANCE findings; one PATCH-tier ADAPT finding deferred to follow-up)."

# =============================================================================
# @kno:index
# =============================================================================
_index:
  - path: "overview"
    line: 298
    keywords: [contract, overview, surface, conversational, self-healing]
  - path: "the-contract"
    line: 332
    keywords: [must, mandate, conformance, requirements]
  - path: "discoverability"
    line: 401
    keywords: [discoverability, enum, oneOf, choices_endpoint, D1]
  - path: "envelopes"
    line: 456
    keywords: [envelope, rest, mcp, a2a, problem-details, jsonrpc]
  - path: "cross-surface-parity"
    line: 536
    keywords: [parity, REST, MCP, A2A, semantic-equivalence, D5]
  - path: "remediation"
    line: 569
    keywords: [remediation, next_action, auto_fix, D3, D4]
  - path: "rubric"
    line: 612
    keywords: [rubric, scoring, maturity, baseline, threshold]
  - path: "bedrock-conformance"
    line: 656
    keywords: [bedrock, P6, P7, P10, schema-minimization, audit]
  - path: "lifecycle"
    line: 752
    keywords: [draft, stable, deprecation, version, status]

# =============================================================================
# @kno:contains
# =============================================================================
contains:
  - xri: "#overview"
    role: section
    title: "Overview"
    keywords: [conversational, self-healing, contract]
  - xri: "#the-contract"
    role: section
    title: "The Contract"
    keywords: [must, mandate, conformance]
  - xri: "#discoverability"
    role: section
    title: "Discoverability Contract"
    keywords: [enum, oneOf, choices_endpoint]
  - xri: "#envelopes"
    role: section
    title: "Envelope Shapes"
    keywords: [REST, MCP, A2A]
  - xri: "#cross-surface-parity"
    role: section
    title: "Cross-Surface Parity"
    keywords: [parity, semantic-equivalence]
  - xri: "#remediation"
    role: section
    title: "Remediation Guidance"
    keywords: [next_action, auto_fix]
  - xri: "#rubric"
    role: section
    title: "Maturity Rubric"
    keywords: [scoring, baseline, threshold]
  - xri: "#bedrock-conformance"
    role: section
    title: "Bedrock Conformance"
    keywords: [P6, P7, P10, schema-minimization]
  - xri: "#lifecycle"
    role: section
    title: "Lifecycle"
    keywords: [draft, stable, deprecation]

# =============================================================================
# SECTION: Overview
# =============================================================================
# @section: overview
# @title: Overview
# =============================================================================

# A "conversational and self-healing" API surface is one where every response —
# success OR failure — carries enough structured signal for the caller (human or
# agent) to make a recoverable decision without escalation. Concretely:
#
#   - On the SUCCESS path, the surface advertises what choices it accepts via
#     `enum` / `oneOf` / `choices_endpoint` on every constrained parameter, so
#     callers don't need to make a wrong call first to learn the valid set.
#
#   - On the FAILURE path, every error response carries:
#       * a stable machine-readable `type` URI
#       * a caller-safe human title and detail
#       * `valid_values` when a constrained input was wrong
#       * `remediation` with a structured `next_action` (URL, scope, or guide)
#       * a `request_id` correlation handle
#       * surface-specific tool/skill pointers (`mcp_tool`, `a2a_skill`)
#
# The contract is realized through three envelope shapes — one per agent-
# consumed surface — but the semantic content is equivalent. A caller resolving
# the same underlying problem on REST, MCP, or A2A receives semantically
# equivalent structured remediation. That cross-surface parity is the unique
# Possibility contribution beyond the upstream standards (RFC 9457, MCP, A2A
# JSON-RPC).
#
# The Self-Healing Maturity Rubric scores each manifest 0–4 on five dimensions
# (D1-D5). The rubric is the yardstick that measures conformance; this spec is
# the contract being measured.

# =============================================================================
# SECTION: The Contract
# =============================================================================
# @section: the-contract
# @title: The Contract
# =============================================================================

# Every public API surface in `content/apis/*.kno` (any manifest where
# `visibility: public` applies per the collection default, or where individual
# operations advertise `mcp.expose: true` or A2A skill projection) MUST satisfy
# the following:
#
# REQUIRED:
#
#   R1. Every constrained-choice parameter MUST expose its valid values
#       through one of three carriers (mutually exclusive):
#         a. `enum: [...]` for closed literal sets
#         b. `oneOf: [...]` for open structurally-distinct alternatives
#         c. `choices_endpoint: /...` for dynamic value sets (registries,
#            tenant-configured options, live catalogs)
#       Enforced by `scripts/lint-discoverability-contract.ts --strict` at
#       pre-commit (#1754).
#
#   R2. Every 4xx response MUST emit the RFC 9457 Problem Details envelope
#       with the Possibility extensions (`valid_values`, `remediation`,
#       `docs_url`, `mcp_tool`, `a2a_skill`, `request_id`) where applicable.
#       Canonical at `docs/architecture/error-envelope-spec.md`.
#
#   R3. Every 5xx response MUST emit the same RFC 9457 envelope or the
#       legacy compatibility shape (transitional alias path). The legacy
#       5xx envelope is documented in error-envelope-spec.md; new code
#       SHOULD emit canonical 9457.
#
#   R4. Every MCP-exposed operation (mcp.expose: true) MUST project the
#       same semantic content through the MCP envelope
#       (`pspace.mcp.error.v1` in `CallToolResult.structuredContent.error`)
#       on tool-call failure. Canonical at
#       `services/pspace-api/src/mcp/error-envelope.ts`.
#
#   R5. Every A2A-exposed operation MUST project the same semantic content
#       through the A2A envelope (`pspace.a2a.error.v1` in
#       JSON-RPC `error.data`) on skill-call failure. Canonical at
#       `services/pspace-api/src/a2a/error-envelope.ts`.
#
#   R6. Cross-surface parity: a single source of truth (the canonical
#       `ProblemDetails` shape on the REST surface) projects into the MCP
#       and A2A surfaces by thin transformation. The cross-surface
#       `auth_ux` parity test
#       (`services/pspace-api/src/a2a/__tests__/error-envelope.test.ts`)
#       freezes the equivalence.
#
# SHOULD:
#
#   S1. APIs SHOULD declare `docs_url` on every distinct problem type so
#       humans land on a documented explanation.
#
#   S2. APIs SHOULD declare `mcp_tool` / `a2a_skill` when an equivalent
#       corrective tool exists on the agent-consumed surface, so callers
#       can switch surfaces without losing the remediation thread.
#
#   S3. APIs SHOULD score ≥ 3 on every rubric dimension after the P4 sweep.
#
# MAY:
#
#   M1. APIs MAY emit `auto_fix_available: true` only when the platform
#       genuinely exposes a bounded corrective action (D4 score 3+).
#       Asserting auto-fix without the action is a contract violation
#       (api-contract-honesty.instructions.md).

# =============================================================================
# SECTION: Discoverability Contract
# =============================================================================
# @section: discoverability
# @title: Discoverability Contract (#1754)
# =============================================================================

# The discoverability contract makes Dimension 1 of the rubric (Discoverability
# of choices) machine-checkable at the .kno manifest layer. Every constrained-
# choice parameter MUST declare its valid values via one of three approved
# carriers, enforced by `scripts/lint-discoverability-contract.ts --strict` at
# pre-commit.
#
# Carriers (mutually exclusive):
#
#   1. `enum: [...]` — closed set of primitive literals. Projected by the
#      MCP transformer into `z.enum(...)` (for string enums) or `z.union(
#      z.literal(...))` (for numeric/boolean/mixed enums). Example:
#
#        - name: auth_ux
#          in: body
#          type: string
#          enum: [hosted, custom]
#
#   2. `oneOf: [...]` — open alternatives where each member is a sub-schema
#      (e.g. either a URL or an XRI). Projected into `z.union(...)` of
#      `z.unknown()` alternatives in v1 (deeper recursion deferred to M45.P3
#      #1758). When alternatives are all literals, prefer `enum`.
#
#   3. `choices_endpoint: /possibilities/:id/roles/options` — companion
#      endpoint for dynamic value sets (registries, tenant config, live
#      catalogs). The endpoint returns the current valid set as
#      `[{value, label?, description?}]`. The schema stays open (no Zod
#      enum), but the parameter description appended with
#      `Valid choices: GET /...` so agents see where to look up values.
#
# Heuristic detection. The lint flags constrained-but-undeclared parameters
# using two heuristics:
#
#   - **Name patterns** (case-insensitive): `type`, `kind`, `mode`, `state`,
#     `status`, `stage`, `phase`, `tier`, `category`, `severity`, `level`,
#     `format`, `policy`, `action`, `verdict`, `visibility`, `scope`,
#     `target`, plus `_*` suffix variants and the canonical `auth_ux`
#     (the gap that motivated M45).
#
#   - **Description phrases**: literal `enum:` token, "supported/valid/
#     allowed/accepted/permitted values", "must be one of" / "must equal"
#     / "must match", "one of ..." followed by quoted literals, "|"
#     separated lists of 3+ short alternatives.
#
# False positives are expected during the first rollout. The lint embeds a
# `PHASE_1_DEFERRED_ALLOWLIST` mapping each pre-existing finding to its
# target P4 sweep issue (#1762 Tier-A, #1763 Tier-B, #1764 Tier-C). New
# violations outside the allowlist fail the build immediately.

# =============================================================================
# SECTION: Envelope Shapes
# =============================================================================
# @section: envelopes
# @title: Envelope Shapes
# =============================================================================

# Three envelope shapes, one contract. Each surface uses its native carrier
# and vocabulary; the semantic content is equivalent.
#
# Canonical reference: docs/architecture/error-envelope-spec.md
#
# REST — RFC 9457 Problem Details (#1751)
# ---------------------------------------
#
# HTTP/1.1 422 Unprocessable Entity
# Content-Type: application/problem+json
#
# {
#   "type": "pspace://problem/invalid_auth_ux",
#   "title": "Invalid auth_ux",
#   "status": 422,
#   "detail": "auth_ux must be one of \"hosted\" or \"custom\".",
#   "instance": "urn:pspace:request:018f6b8a-2c42-7f44-8c47-5dfb5c0aa111",
#   "code": "invalid_auth_ux",
#   "request_id": "018f6b8a-2c42-7f44-8c47-5dfb5c0aa111",
#   "valid_values": { "auth_ux": ["hosted", "custom"] },
#   "remediation": {
#     "type": "request_scope_elevation",
#     "message": "Set auth_ux to \"hosted\" or \"custom\", then retry.",
#     "next_action": {
#       "endpoint_url": "/possibilities/{id}/auth",
#       "guide_xri": "pspace://guide:branded-oidc-login"
#     },
#     "example_request": {
#       "method": "PATCH",
#       "path": "/possibilities/{id}/auth",
#       "body": { "auth_ux": "custom" }
#     },
#     "auto_fix_available": false
#   },
#   "docs_url": "https://possibility.space/docs/guides/branded-oidc-login#auth-ux",
#   "mcp_tool": "update_possibility_auth",
#   "a2a_skill": "possibility_auth_configuration"
# }
#
# MCP — pspace.mcp.error.v1 (#1752)
# ---------------------------------
#
# Tool call result with `isError: true`. The Problem Details payload is
# preserved verbatim inside `structuredContent.error`, with surface-specific
# extensions:
#   - `surface: "mcp"` marker
#   - `suggested_tools[]` — MCP tools the caller can invoke to recover
#   - `corrected_args` — agent-friendly args to retry the failed call
#   - `machine_hints` — non-cardinal hints (retryable, severity, field_paths)
#
# A2A — pspace.a2a.error.v1 (#1753)
# ---------------------------------
#
# JSON-RPC 2.0 error response. The Possibility envelope rides in
# `error.data`. JSON-RPC error code derived from Problem `status` per the
# `jsonRpcCodeForProblem()` table:
#
#   422 → InvalidParams (-32602)
#   401 → AuthenticationRequired (-32001)
#   403 → AuthorizationFailed (-32004)
#   409 → InvalidTaskState (-32005)
#   415 → ContentTypeNotSupported (-32007)
#   429 → RateLimitExceeded (-32008)
#   501 → OperationNotSupported (-32009)
#   503 → ResourceUnavailable (-32010)
#   "task_not_found" (any) → TaskNotFound (-32003)
#
# Surface-specific extensions on A2A:
#   - `surface: "a2a"` marker
#   - `suggested_skills[]` — A2A skills the caller can invoke
#   - `corrected_params` — JSON-RPC-friendly retry parameters
#   - `machine_hints` with `category` (validation/auth/task/...)

# =============================================================================
# SECTION: Cross-Surface Parity
# =============================================================================
# @section: cross-surface-parity
# @title: Cross-Surface Parity (Dimension 5)
# =============================================================================

# A single source of truth (the canonical `ProblemDetails` shape) projects
# into the MCP and A2A envelopes by thin transformation (P10). The same
# underlying problem yields semantically equivalent envelopes on all three
# surfaces.
#
# Parity invariants (frozen by the cross-surface test in
# `services/pspace-api/src/a2a/__tests__/error-envelope.test.ts`):
#
#   - `problem.type`        equivalent across REST / MCP / A2A
#   - `problem.code`        equivalent
#   - `problem.status`      preserved (or projected to JSON-RPC code on A2A)
#   - `valid_values`        identical content
#   - `remediation`         identical content
#   - `documentation_uri`   identical content (REST: `docs_url`)
#   - `mcp_tool`            preserved on REST + MCP envelopes
#   - `a2a_skill`           preserved on REST + A2A envelopes
#
# Surface-native renames (intentional, not drift):
#
#   - `suggested_tools`  (MCP) ↔ `suggested_skills` (A2A)
#   - `corrected_args`   (MCP) ↔ `corrected_params` (A2A)
#   - `docs_url`         (REST) ↔ `documentation_uri` (MCP/A2A)
#
# Renames reflect surface conventions; the underlying semantic content is
# equivalent and the parity test asserts the equivalence by construction.

# =============================================================================
# SECTION: Remediation Guidance
# =============================================================================
# @section: remediation
# @title: Remediation Guidance (Dimensions 3 + 4)
# =============================================================================

# Remediation is the structured "what should the caller do next" pointer. It
# follows the discriminated taxonomy defined in
# `content/knowledge-base/remediation-block-pattern.kno` (source of truth for
# the `remediation.type` discriminator).
#
# Types (closed set):
#
#   - `wait_for_provisioning`     async work in flight; caller polls
#   - `request_scope_elevation`   needs token with broader scope
#   - `switch_user`               authentication context mismatch
#   - `register_custom_domain`    tenant action required first
#   - `none`                      honest closure — no caller action exists
#
# When `type: none`, `reason` is REQUIRED and MUST be one of:
#
#   - `no_public_equivalent_exists`
#   - `auth_required_for_safety`
#   - `not_yet_implemented`
#
# `next_action` (optional, structured) points the caller at the next call:
#
#   {
#     "endpoint_xri": "pspace://api-endpoint/possibilities-create",
#     "endpoint_url": "/possibilities",
#     "required_scope": "pspace:possibility.write",
#     "guide_xri": "pspace://guide:create-possibility"
#   }
#
# `example_request` (optional, safe sample) shows the corrected call shape.
# MUST NOT carry secrets or tenant-identifiable data.
#
# `auto_fix_available: true` is the D4 (Auto-fix capability) advertisement.
# Setting it true commits the platform to expose a bounded corrective action
# the caller can invoke. Asserting auto-fix without the corresponding tool/
# endpoint is banned by `api-contract-honesty.instructions.md`.

# =============================================================================
# SECTION: Maturity Rubric
# =============================================================================
# @section: rubric
# @title: Maturity Rubric (5 Dimensions, 0-4 Scale)
# =============================================================================

# The Self-Healing Maturity Rubric scores each `content/apis/*.kno` manifest
# against this contract. Canonical at
# `docs/architecture/self-healing-maturity-rubric.md`.
#
# Dimensions:
#
#   D1 Discoverability of choices — enum / oneOf / choices_endpoint on every
#      constrained parameter. Scored 0 (guess required) to 4 (structured,
#      bounded, defaulted, exposed on agent surface, connected to a
#      recoverable workflow).
#
#   D2 Error clarity — structured Problem Details with discriminated codes.
#      Scored 0 (generic) to 4 (typed result objects with layered validation
#      outcomes).
#
#   D3 Remediation guidance — `remediation.next_action` per error variant.
#      Scored 0 (no recovery path) to 4 (closed workflow with verifiable
#      remediation result).
#
#   D4 Auto-fix capability — bounded self-healing actions. Scored 0
#      (observational only) to 4 (diagnose → apply → verify).
#
#   D5 Cross-surface parity — REST + MCP + A2A projecting one source of
#      truth. Scored 0 (one surface) to 4 (four-surface projection
#      explicitly derived, identity/content parity preserved).
#
# Threshold for Phase 4 completion: every manifest satisfies every applicable
# dimension at ≥ 3; N/A dimensions satisfy the threshold by construction. The
# P4 sweeps (#1762 Tier-A, #1763 Tier-B, #1764 Tier-C) bring each tier up to threshold.
#
# The scorer (#1749, `scripts/score-self-healing-maturity.ts`) derives
# scores from explicit manifest fields per P10 — `parameters[].enum`,
# response body examples, `remediation_default`, `error_responses`,
# `mcp.expose`, public surface declarations. Do NOT add a manual
# `self_healing_score` field to manifests; the score is derived
# structure (P10) over corpus evidence (P6).

# =============================================================================
# SECTION: Bedrock Conformance
# =============================================================================
# @section: bedrock-conformance
# @title: Bedrock Conformance
# =============================================================================

# This spec is anchored to four bedrock concepts. The mapping documents how
# the conversational-surface contract operationalizes each one.
#
# P6 (Morphological / Emergent corpus-level patterns)
# ---------------------------------------------------
#
# The rubric scores patterns ACROSS the corpus of API manifests, not on
# any single exemplar. Discoverability gaps, error-clarity gaps, and parity
# gaps surface as corpus-level findings (32 discoverability findings at
# audit time, routed to P4 sweeps). The contract is meaningful only at
# corpus scale: a single API with a `valid_values` envelope is undiscoverable
# in isolation; 59 APIs uniformly emitting the envelope makes the discoverable
# pattern emerge.
#
# P7 (Cooperative / Codependent relationships)
# --------------------------------------------
#
# Cross-surface parity is a P7 invariant: the REST envelope `documents` the
# MCP envelope (via `mcp_tool`), the REST envelope `documents` the A2A
# envelope (via `a2a_skill`), and the discoverability contract `documents`
# the rubric (via D1 evidence). The relationship graph is bidirectional:
# the rubric scores against this spec; this spec references the rubric.
# Neither artifact stands alone.
#
# P10 (Derivable Structure)
# -------------------------
#
# MCP and A2A envelopes are P10 thin transformations of the canonical
# `ProblemDetails` shape — no parallel vocabulary, no hand-maintained
# duplication. The `kno-tool-transformer` reads `enum` / `oneOf` /
# `choices_endpoint` from the .kno manifest and derives MCP `inputSchema`
# constraints. The rubric scores are derived from explicit fields in the
# manifest, never hand-authored. Per-API maturity is derivable from the
# manifest alone, not from runtime probing.
#
# § 0.6 Schema Minimization Principle
# -----------------------------------
#
# This spec does NOT introduce a new entity-type schema. No .kno files
# declare `$schema: conversational-surface@0.1.1`. The contract is realized
# through:
#
#   - api-spec.kno v0.6.0 (the `enum` / `oneOf` / `choices_endpoint` fields)
#   - error-envelope-spec.md (the REST envelope reference)
#   - The two TypeScript envelope files (`mcp/error-envelope.ts`,
#     `a2a/error-envelope.ts`)
#   - The maturity rubric markdown
#   - The discoverability lint
#
# This spec is the discoverable umbrella — like `otel-spec.kno` for
# observability — that ties the existing artifacts together. Passing the
# three-gate test (Gate 1 Distinctness, Gate 2 Reusability, Gate 3 Clarity)
# is what justifies the umbrella over scattered references.
#
# Bidirectional audit
# -------------------
#
# A bidirectional bedrock conformance audit was conducted during authoring
# per `.github/instructions/bedrock-conformance-audit.instructions.md`.
#
# Bedrock versions at audit time:
#   - Foundational Principles: v1.26.0 (2026-05-11)
#   - Format Requirements: v0.10.1 (2026-05-09)
#   - System Architecture: v1.16.1 (2026-05-09)
#
# Audit summary:
#
# | Direction                  | Findings    | Notes                                                                 |
# | -------------------------- | ----------- | --------------------------------------------------------------------- |
# | Spec→Bedrock (CONFORMANCE) | 0 findings  | Spec aligns with P6, P7, P10, § 0.6. No misalignment surfaced.        |
# | Bedrock→Spec (ADAPT)       | 1 finding   | ADAPT-01 — PATCH-tier cross-reference (see below). Not blocking.      |
# | Paired findings            | 0 pairs     |                                                                       |
#
# ADAPT-01 (deferred):
#   - Document: kno-foundational-principles.md
#   - Section: P6 (Morphological / Emergent) cross-reference table
#   - Classification: ADAPT (bedrock SHOULD evolve, PATCH-tier)
#   - Finding: P6's existing cross-reference table cites P10 derivable
#     structure but does not yet reference the conversational-surface
#     spec as an additional corpus-level pattern instance. The Self-
#     Healing Maturity Rubric is a P6 worked example (corpus-first scoring,
#     emergent gap detection) but isn't named in the principle body.
#   - Recommendation: Add the rubric to P6's worked-examples list as a
#     PATCH bump when the next bedrock edit lands. No spec change required.
#   - Disposition: Deferred — does not block Draft → Stable transition.
#     Tracked at issue #2884 (filed 2026-05-19 alongside this spec).
#
# Three-gate test result: PASS (all three gates cleared — see file header).

# =============================================================================
# SECTION: Lifecycle
# =============================================================================
# @section: lifecycle
# @title: Lifecycle & Versioning
# =============================================================================

# Status transitions:
#
#   0.1.0 Draft       — initial codification of the contract (this version)
#                       Phase 2 substrate (envelopes + discoverability)
#                       complete; Phase 3 platform plumbing pending.
#
#   1.0.0 Stable      — gated by Phase 3 plumbing (#1756-#1761) AND an
#                       end-of-Epic code-auditor pass per the
#                       `code-auditor` skill. Stable requires:
#                         - kno-router middleware emits the envelope
#                           automatically on every 4xx/5xx (#1756, #1757)
#                         - kno-tool-transformer wraps MCP (#1758)
#                         - A2A skill wrapper does the same (#1759)
#                         - admin UI renders What/Why/Try-this (#1760)
#                         - docs site deep-links from error codes (#1761)
#                         - per-API sweeps (#1762-#1764) bring corpus to
#                           rubric threshold (≥ 3 on every applicable dimension; N/A passes)
#                         - end-of-Epic code-auditor confirms.
#
# Versioning conventions (per kno-spec):
#
#   - PATCH (0.1.X) — clarifications, examples, audit-driven cross-refs
#   - MINOR (0.X.0) — additive sections, new envelope extensions, additive
#                     rubric dimension
#   - MAJOR (X.0.0) — breaking change to envelope shapes, required-field
#                     additions, contract narrowings that affect callers
#
# Deprecation: when a section, requirement, or envelope field is
# deprecated, mark it `deprecated: <date>` with a migration note and a
# successor reference. Do not silently remove.

# =============================================================================
# Closing
# =============================================================================
#
# The conversational + self-healing contract is the floor every Possibility
# API surface stands on. Manifest authors get the contract for free by
# following `api-spec.kno` (the discoverability fields), the platform
# emitters (Phase 3 plumbing), and the linter (Phase 2 discoverability
# enforcement). Integrators consume the contract through three native
# envelope shapes that say the same thing the same way.
#
# When something breaks, the response carries enough structured signal that
# the caller — human or agent — can recover without escalation. That is the
# self-healing part. When something might break, the manifest carries enough
# structured signal that the caller can avoid the breakage in the first
# place. That is the discoverability part. Together they make the surface
# conversational.