$schema: "https://json-schema.org/draft/2020-12/schema"
$id: "https://cfse.ai/schemas/artifacts/entry_point.schema.yaml"
title: "CFSE Entry Point (EP) Artifact Schema"
description: |
  Schema for Entry Point artifacts (EP-*).

  An Entry Point is a first-class, standalone definition of a surface:
  how it is accessed (method/protocol + path), what inputs it accepts,
  what it can expose, and where it can be exercised in the real world
  via tangible access locators.

type: object

required:
  - id
  - title
  - owner_concept
  - method
  - path
  - action

properties:
  id:
    $ref: "https://cfse.ai/schemas/grammar.schema.yaml#/$defs/EntryPointID"
    description: "Unique identifier for this entry point (EP-*)"

  title:
    type: string
    minLength: 1
    maxLength: 120
    description: "Human-readable name of the surface"

  owner_concept:
    $ref: "https://cfse.ai/schemas/grammar.schema.yaml#/$defs/ConceptID"
    description: |
      The concept that owns this entry point. This is the primary concept
      whose instances are created/read/updated/deleted or whose surface is rendered.

  description:
    type: string
    description: "Optional narrative description of the surface."

  method:
    type: string
    enum:
      - GET
      - POST
      - PUT
      - PATCH
      - DELETE
      - GraphQL
      - gRPC
      - WebSocket
      - CLI
      - Event
    description: "HTTP method, protocol type, or trigger type"

  path:
    type: string
    minLength: 1
    description: "Path/pattern, GraphQL operation, event name, or CLI command pattern"

  action:
    $ref: "https://cfse.ai/schemas/grammar.schema.yaml#/$defs/ActionType"
    description: "High-level operation type (CREATE, READ, UPDATE, DELETE, ACCESS, EXECUTE, etc.)"

  auth_required:
    type: boolean
    default: true
    description: "Whether authentication is required to access this entry point"

  permissions:
    type: array
    items:
      type: string
    description: "Required permissions/roles (if applicable)"

  parameters:
    type: array
    items:
      $ref: "https://cfse.ai/schemas/grammar.schema.yaml#/$defs/Parameter"
    description: "Input parameters for this entry point"

  attacker_controlled_inputs:
    type: array
    items:
      type: string
    description: |
      Optional list of attacker-controlled input names (usually a subset of parameters).
      This is descriptive metadata to aid threat modeling; it does not encode policy.

  tangible_locations:
    type: array
    items:
      $ref: "https://cfse.ai/schemas/grammar.schema.yaml#/$defs/TangibleLocation"
    description: "Concrete access locators (URLs, CLI invocations, etc.) for this entry point"

  exposes:
    type: array
    items:
      $ref: "#/$defs/Exposure"
    description: |
      Optional viewer-agnostic exposure inventory: what this surface can disclose/derive/link/emit
      in some context. This MUST NOT encode executable policy logic.

  governed_by_invariants:
    type: array
    items:
      $ref: "https://cfse.ai/schemas/grammar.schema.yaml#/$defs/InvariantID"
    description: |
      Invariants that govern whether/how this surface is permitted or constrained
      (traceability only; invariants carry the logic).

  notes:
    type: string
    description: "Additional scoping notes"

  status:
    $ref: "https://cfse.ai/schemas/grammar.schema.yaml#/$defs/ArtifactStatus"
    default: "DRAFT"

  version:
    type: string
    pattern: "^[0-9]+\\.[0-9]+\\.[0-9]+$"

  extensions:
    $ref: "https://cfse.ai/schemas/grammar.schema.yaml#/$defs/Extensions"

additionalProperties: false

$defs:
  ExposureMode:
    type: string
    enum:
      - DISCLOSE
      - DERIVE
      - LINK
      - METADATA

  ExposureEvidence:
    type: object
    properties:
      code_refs:
        type: array
        items:
          type: string
        description: "File/line references, URLs, or other implementation pointers"
      notes:
        type: string
    additionalProperties: false

  Exposure:
    type: object
    required:
      - ref
      - exposure_mode
    properties:
      ref:
        type: string
        description: "Reference to the exposed item (e.g., C-SYS-USER.email)"
      exposure_mode:
        $ref: "#/$defs/ExposureMode"
      governed_by_invariants:
        type: array
        items:
          $ref: "https://cfse.ai/schemas/grammar.schema.yaml#/$defs/InvariantID"
        description: "Invariants that govern whether/how the exposure is permitted (traceability only)"
      evidence:
        $ref: "#/$defs/ExposureEvidence"
    additionalProperties: false