# Possibility Domain Schema — Layer 2 Entity Type
# KNO Schema Version: 0.2.0
#
# Layer 2 domain schema for Possibility entities — structured ideas/ventures
# with members, services, and federated identity.
#
# A Possibility is the core domain concept in Possibility: a structured idea
# that can attract contributors, provisioned services, and evolve from concept
# to operating venture.
#
# EXTENDS: document-schema.kno (Layer 2 base)
# COMPOSES: identity-schema, history-schema, quality-schema (Layer 1)
# ENABLES: Possibility instances in content/possibilities/
#
# KEY DESIGN DECISIONS:
#   - members[] provides implicit group — no separate group entity needed
#   - members use possibility-axis roles: organizer | contributor (#307)
#   - services[] from FEDERATED tier links to service-config entities
#   - Lightweight compared to organization-schema (no legal/ownership facets)
#   - Owner is a user XRI reference, not embedded user data
#
# THREE-GATE TEST:
#   Gate 1 (Distinctness): YES — a possibility is fundamentally different from
#     an organization (lightweight venture vs legal entity with governance)
#   Gate 2 (Reusability): YES — every user idea is a possibility; core concept
#   Gate 3 (Clarity): YES — first-class entity in the domain model

# =============================================================================
# SCHEMA DECLARATION (RFC-007)
# =============================================================================
$schema: kno@0.0.9

# =============================================================================
# IDENTITY (Layer 1)
# =============================================================================
id: 01KGXP3F5T8KV2NQ4R7WJBM6YH
slug: possibility-schema
type: spec
version: 0.2.0

# =============================================================================
# STANDARD TIER
# =============================================================================
title: "Possibility Domain Schema"
purpose: |
  Define the schema for Possibility entities — structured ideas/ventures that
  can attract contributors, receive provisioned services, and evolve into
  operating ventures.

  **What is a Possibility?**
  A Possibility is the atomic unit of venture in the Possibility platform.
  It represents a structured idea with:
  - An owner and optional members (implicit group)
  - Provisioned services (auth, storage, database, etc.)
  - Federated identity for cross-system resolution
  - Lifecycle status tracking from concept to operation

  **Distinction from Organization:**

  | Aspect | Possibility | Organization |
  |--------|------------|--------------|
  | Weight | Lightweight | Heavyweight |
  | Legal entity | No | Yes (entity_type, jurisdiction) |
  | Governance | Implicit (owner + members) | Formal (governance docs) |
  | Ownership | Single owner XRI | Founders, cap table |
  | Services | Provisioned via services[] | N/A |
  | Purpose | Structured venture/idea | Legal/operational container |

  **Implicit Group Model:**
  A possibility's `members[]` field serves as the group. There is no separate
  group entity — the group is derived from shared participation in a
  possibility. This follows the Schema Minimization Principle (§0.6).

  **FEDERATED Tier:**
  Possibilities are FEDERATED entities — they have `services[]`, `identity`,
  and `resolution` fields from the kno-spec FEDERATED tier. The `services[]`
  array links to service-config entities that describe provisioned services.

  **Layer 2 Position:** Possibility extends document-schema (Layer 2), which
  composes identity, history, and quality (Layer 1).

# =============================================================================
# RICH TIER — Provenance & Taxonomy
# =============================================================================
provenance:
  origin:
    id: 01KGXP3F5T8KV2NQ4R7WJBM6YH
    timestamp: "2026-02-17T00:00:00Z"
    tool: manual

taxonomy:
  topics:
    - entities
    - ventures
    - possibilities
    - domain-schemas
    - federated-identity
    - service-provisioning
  keywords:
    - possibility
    - venture
    - idea
    - project
    - members
    - services
    - provisioning
    - federated

# =============================================================================
# RICH TIER — Relationships
# =============================================================================
relationships:
  extends:
    - xri: "kno://specs/document-schema"
      reason: "Layer 2 base type for textual entities"

  depends_on:
    - xri: "kno://specs/kno-spec"
      reason: "Conforms to KNO format specification v0.0.9"

  composes:
    - xri: "kno://specs/identity-schema"
      reason: "Layer 1: id, slug, name, provenance, equiv_ids"
    - xri: "kno://specs/history-schema"
      reason: "Layer 1: _history, changelog"
    - xri: "kno://specs/quality-schema"
      reason: "Layer 1: quality, validation"

  related_to:
    - xri: "kno://specs/user-schema"
      reason: "Users own and participate in possibilities"
    - xri: "kno://specs/organization-schema"
      reason: "Sibling L2 domain schema — heavyweight legal container vs lightweight venture"
    - xri: "kno://specs/service-config-schema"
      reason: "services[] entries reference service-config entities"
    - xri: "kno://specs/capability-schema"
      reason: "Provisioning capabilities gate who can create/manage possibilities"
    - xri: "kno://specs/role-schema"
      reason: "Members have roles within a possibility"

  enables:
    - xri: "kno://content/possibilities/*"
      reason: "Possibility instance files"

  implements:
    - xri: "kno://rfcs/RFC-013"
      reason: "Identity Separation — ULID birth identity, mutable slug/name"

# =============================================================================
# RICH TIER — Quality
# =============================================================================
quality:
  completeness: 0.85
  last_reviewed: "2026-02-17"
  review_status: draft
  reviewed_by: "claude"

# =============================================================================
# HISTORY (P9 Temporal)
# =============================================================================
_history:
  retention: full
  format: changelog

  changelog:
    - version: "0.1.0"
      date: "2026-02-17"
      author: "claude"
      summary: "Initial possibility domain schema"
      changes:
        - "Created for auth-as-a-service-v1 milestone (Phase 1)"
        - "L2 domain schema with members[] for implicit group model"
        - "FEDERATED tier: services[], identity, resolution"
        - "Resolves dangling reference from identity-schema enables[]"
        - "Three-gate test documented in header comments"

# =============================================================================
# SPECIFICATION CONTENT
# =============================================================================
spec:
  status: Draft

  description: |
    ## Possibility Entity Structure

    A Possibility entity represents a structured venture/idea. It is the core
    domain concept and the primary unit of tenancy for provisioned services.

    ### Layer Architecture

    ```
    ┌─────────────────────────────────────────────────────────────────────┐
    │  POSSIBILITY ENTITY                                                │
    ├─────────────────────────────────────────────────────────────────────┤
    │                                                                     │
    │  BASIC TIER (required)                                              │
    │  ├── $schema: "possibility@0.1"                                     │
    │  ├── id: "01KGXYZ..." (ULID)                                        │
    │  ├── type: "possibility"                                            │
    │  └── version: "1.0.0"                                               │
    │                                                                     │
    │  STANDARD TIER                                                      │
    │  ├── slug: "artisan-marketplace"                                    │
    │  ├── title: "Artisan Marketplace"                                   │
    │  ├── name: "Artisan Marketplace"                                    │
    │  └── purpose: "Connect local artisans with buyers"                  │
    │                                                                     │
    │  RICH TIER                                                          │
    │  ├── taxonomy: { topics, keywords }                                 │
    │  ├── relationships: { owned_by, has_member, uses }                  │
    │  └── quality: { completeness, review_status }                       │
    │                                                                     │
    │  DOMAIN FIELDS                                                      │
    │  ├── owner: "pspace://user:01KGABC..." (XRI)                        │
    │  ├── status: "active"                                               │
    │  ├── lifecycle: "building"                                          │
    │  ├── description: "A marketplace for..."                            │
    │  ├── members[]:                                                     │
    │  │   ├── user_xri: "pspace://user:01KG..."                          │
    │  │   ├── role: "contributor"                                        │
    │  │   └── joined_at: "2026-02-17T..."                                │
    │  └── tags[]: ["marketplace", "artisan", "local"]                    │
    │                                                                     │
    │  FEDERATED TIER                                                     │
    │  ├── identity:                                                      │
    │  │   ├── canonical_id: "01KGXYZ..."                                  │
    │  │   └── equiv_ids[]: [{ provider, id }]                            │
    │  ├── services[]:                                                    │
    │  │   ├── type: "pspace:auth"                                        │
    │  │   ├── provider: "keycloak"                                       │
    │  │   ├── config_xri: "pspace://service-config:01KG..."              │
    │  │   └── endpoints[]: ["https://auth.possibility.space"]            │
    │  └── resolution:                                                    │
    │      ├── resolver_uri: "https://api.possibility.space/resolve"      │
    │      └── status: "active"                                           │
    │                                                                     │
    └─────────────────────────────────────────────────────────────────────┘
    ```

    ### Implicit Group Model

    The `members[]` field provides group semantics without a separate group
    entity. A possibility's members ARE its group:

    - The **owner** is always an implicit admin-level member
    - Additional **members** have roles (contributor, viewer, etc.)
    - Group identity is derived from the possibility's identity
    - No separate group creation, lifecycle, or management needed

    This follows the Schema Minimization Principle: organization-schema
    handles heavyweight containers (legal entities), and possibility
    members[] handles lightweight collaboration groups.

    ### Service Bindings

    The `services[]` array in the FEDERATED tier links to service-config
    entities. Each entry describes a provisioned service:

    ```yaml
    services:
      - type: "pspace:auth"
        provider: "keycloak"
        config_xri: "pspace://service-config:01KGABC..."
        endpoints:
          - "https://auth.possibility.space"
        status: "active"
      - type: "pspace:storage"
        provider: "minio"
        config_xri: "pspace://service-config:01KGDEF..."
        endpoints:
          - "https://storage.possibility.space"
        status: "active"
    ```

    The `config_xri` points to a service-config-schema entity that holds
    the full configuration (credentials reference, provider details, etc.).

  schema:
    type: object
    required:
      - id
      - slug
      - title
      - owner
      - status

    properties:
      # -----------------------------------------------------------------------
      # BASIC TIER
      # -----------------------------------------------------------------------
      $schema:
        type: string
        const: "possibility@0.1.0"
        description: "Schema declaration"

      id:
        type: string
        format: ulid
        immutable: true
        description: |
          Unique identifier (ULID). Immutable birth identity per RFC-013.
          Example: "01KGXP3F5T8KV2NQ4R7WJBM6YH" # pragma: allowlist secret

      type:
        type: string
        const: "possibility"
        description: "Entity type identifier"

      version:
        type: string
        format: semver
        description: "Entity instance version (not schema version)"

      # -----------------------------------------------------------------------
      # STANDARD TIER
      # -----------------------------------------------------------------------
      slug:
        type: string
        format: kebab-case
        pattern: "^[a-z0-9]+(-[a-z0-9]+)*$"
        mutable: true
        description: "Human-readable URL-safe identifier. Mutable per RFC-013."
        examples:
          - "artisan-marketplace"
          - "community-garden-app"

      title:
        type: string
        description: "Display title for the possibility"
        examples:
          - "Artisan Marketplace"
          - "Community Garden App"

      name:
        type: string
        mutable: true
        description: "Display name (can include spaces, special characters)"

      purpose:
        type: string
        description: "Brief description of what this possibility is about"

      # -----------------------------------------------------------------------
      # DOMAIN FIELDS
      # -----------------------------------------------------------------------
      owner:
        type: string
        format: xri
        description: |
          XRI reference to the user who owns this possibility.
          The owner has full control and is always an implicit admin-level member.
          Example: "pspace://user:01KGABC123DEF456"
        examples:
          - "pspace://user:01KGABC123DEF456"
          - "pspace://user:max-engel"

      status:
        type: string
        enum:
          - draft
          - active
          - paused
          - archived
          - deprecated
        description: |
          Current operational status.

          | Status | Meaning |
          |--------|---------|
          | draft | Idea stage, not yet active |
          | active | Operating, services may be provisioned |
          | paused | Temporarily inactive |
          | archived | No longer active, preserved for reference |
          | deprecated | Being phased out, may have successor |

      lifecycle:
        type: string
        enum:
          - ideation
          - validating
          - building
          - operating
          - scaling
          - sunsetting
        description: |
          Current lifecycle stage.

          | Stage | Description |
          |-------|-------------|
          | ideation | Exploring the concept |
          | validating | Testing assumptions |
          | building | Developing the product/service |
          | operating | Running and serving users |
          | scaling | Growing beyond initial scope |
          | sunsetting | Winding down operations |

      description:
        type: string
        format: markdown
        description: "Extended description supporting markdown formatting"

      tags:
        type: array
        items:
          type: string
        description: "Freeform tags for categorization and discovery"
        examples:
          - ["marketplace", "artisan", "local-commerce"]

      # -----------------------------------------------------------------------
      # MEMBERS (Implicit Group) — Two-Axis Role Model (#307)
      # -----------------------------------------------------------------------
      members:
        type: array
        description: |
          List of users who participate in this possibility. The members[]
          array IS the group — no separate group entity needed.

          Uses the possibility-axis of the two-axis role model:
            - organizer: creator/manager with full control
            - contributor: scoped worker with read/write access

          Ownership invariants:
            1. A possibility MUST have at least one organizer
            2. The last organizer CANNOT be removed (must transfer first)
            3. Only organizers and platform admins can transfer organizer role
            4. A possibility can have multiple organizers (co-ownership)
            5. Ownership transfer is explicit (not implicit from removal)

          The owner (from top-level `owner` field) is always an implicit
          organizer even if not listed in members[].
        items:
          type: object
          required:
            - user_xri
            - role
          properties:
            user_xri:
              type: string
              format: xri
              description: "XRI reference to the member user"
              examples:
                - "pspace://user/01KGABC123DEF456"

            role:
              type: string
              enum:
                - organizer
                - contributor
              description: |
                Member's role within this possibility (possibility-axis).
                - organizer: full control — settings, members, services, deletion
                - contributor: scoped worker — read/write content and services
                Maps to pspace:organizer and pspace:contributor capability sets.
              examples:
                - "organizer"
                - "contributor"

            granted_at:
              type: string
              format: date-time
              description: "When this membership was granted"

            granted_by:
              type: string
              format: xri
              description: |
                XRI of the user who granted this membership.
                Present on all non-founder members. May be omitted for the
                original creator (who becomes organizer automatically).

      # -----------------------------------------------------------------------
      # FEDERATED TIER
      # -----------------------------------------------------------------------
      identity:
        type: object
        description: "Federated identity fields from kno-spec FEDERATED tier"
        properties:
          canonical_id:
            type: string
            format: ulid
            description: "Same as top-level id (ULID birth identity)"

          local_ids:
            type: array
            items:
              type: string
            description: "Human-friendly aliases"

          equiv_ids:
            type: array
            items:
              type: object
              properties:
                provider:
                  type: string
                  description: "External system (github, keycloak, etc.)"
                id:
                  type: string
                  description: "Identifier in that system"
                verified:
                  type: boolean
                  description: "Whether equivalence is verified"

      services:
        type: array
        description: |
          Provisioned service bindings. Each entry is a Service Endpoint
          Descriptor (SEP) from the FEDERATED tier, with an added config_xri
          that points to the full service-config entity.
        items:
          type: object
          required:
            - type
            - provider
          properties:
            type:
              type: string
              description: "Service type (URN-style)"
              examples:
                - "pspace:auth"
                - "pspace:storage"
                - "pspace:database"

            provider:
              type: string
              description: "Service provider identifier"
              examples:
                - "keycloak"
                - "minio"
                - "postgres"

            config_xri:
              type: string
              format: xri
              description: |
                XRI reference to the service-config entity with full details.
                Example: "pspace://service-config:01KGABC..."
              examples:
                - "pspace://service-config:01KGABC123DEF456"

            endpoints:
              type: array
              items:
                type: string
                format: uri
              description: "Concrete endpoint URIs"
              examples:
                - ["https://auth.possibility.space"]

            status:
              type: string
              enum:
                - provisioning
                - active
                - degraded
                - deprovisioning
                - inactive
              description: "Current service status"

      resolution:
        type: object
        description: "Entity resolution metadata from kno-spec FEDERATED tier"
        properties:
          resolver_uri:
            type: string
            format: uri
            description: "URI to resolve this entity's full descriptor"
          status:
            type: string
            enum:
              - active
              - redirect
              - deprecated
              - reserved
            description: "Resolution status"

# =============================================================================
# EXAMPLES
# =============================================================================
examples:
  - title: "Minimal Possibility"
    description: "The bare minimum for a valid possibility entity"
    content: |
      $schema: possibility@0.1.0
      id: 01KGXP3F5T8KV2NQ4R7WJBM6YH
      type: possibility
      version: 1.0.0
      slug: artisan-marketplace
      title: "Artisan Marketplace"
      owner: "pspace://user:01KGABC123DEF456"
      status: active

  - title: "Full Possibility with Services"
    description: "A possibility with members and provisioned services"
    content: |
      $schema: possibility@0.1.0
      id: 01KGXP3F5T8KV2NQ4R7WJBM6YH
      type: possibility
      version: 1.0.0

      slug: artisan-marketplace
      title: "Artisan Marketplace"
      name: "Artisan Marketplace"
      purpose: "Connect local artisans with buyers through a curated online marketplace"

      owner: "pspace://user:01KGABC123DEF456"
      status: active
      lifecycle: building
      description: |
        A marketplace platform connecting local artisans with buyers
        who value handcrafted, locally-sourced goods.
      tags:
        - marketplace
        - artisan
        - local-commerce
        - handmade

      members:
        - user_xri: "pspace://user/01KGABC123DEF456"
          role: organizer
          granted_at: "2026-01-15T00:00:00Z"
        - user_xri: "pspace://user/01KGDEF789GHI012"
          role: contributor
          granted_at: "2026-02-01T10:00:00Z"
          granted_by: "pspace://user/01KGABC123DEF456"
        - user_xri: "pspace://user/01KGGHI345JKL678"
          role: contributor
          granted_at: "2026-02-10T14:30:00Z"
          granted_by: "pspace://user/01KGABC123DEF456"

      identity:
        canonical_id: "01KGXP3F5T8KV2NQ4R7WJBM6YH"
        equiv_ids:
          - provider: github
            id: "artisan-marketplace"
            verified: false

      services:
        - type: "pspace:auth"
          provider: keycloak
          config_xri: "pspace://service-config:01KGSVC1AUTH"
          endpoints:
            - "https://auth.possibility.space"
          status: active

      resolution:
        resolver_uri: "https://api.possibility.space/resolve"
        status: active

# =============================================================================
# VALIDATION RULES
# =============================================================================
validation:
  rules:
    - name: "id_required"
      severity: error
      message: "Possibility must have an id"
      check: "exists(id)"

    - name: "owner_required"
      severity: error
      message: "Possibility must have an owner XRI"
      check: "exists(owner)"

    - name: "owner_xri_format"
      severity: error
      message: "Owner must be a valid user XRI"
      check: "matches(owner, '^pspace://user:')"

    - name: "status_required"
      severity: error
      message: "Possibility must have a status"
      check: "exists(status)"

    - name: "members_have_roles"
      severity: error
      message: "Each member must have a user_xri and role"
      check: "all(members, exists(user_xri) && exists(role))"
      when: "exists(members)"

    - name: "service_config_refs"
      severity: warning
      message: "Service entries should have config_xri for full configuration"
      check: "all(services, exists(config_xri))"
      when: "exists(services)"

# =============================================================================
# SOURCE (P4)
# =============================================================================
source: |
  # This schema was created for the auth-as-a-service-v1 milestone.
  # It fulfills the dangling reference from identity-schema.kno:
  #   enables: kno://specs/possibility-schema
  #
  # Design decisions:
  # - members[] for implicit group (no separate group-schema)
  # - services[] from FEDERATED tier for service bindings
  # - Lightweight vs organization-schema (no legal/ownership/governance)
  # - Owner is a user XRI, not embedded user data

source_format: yaml
source_hash: "sha256:tbd"

# =============================================================================
# CONTAINER TIER — Navigation Index
# =============================================================================
_index:
  - path: "identity"
    line: 37
    keywords: [id, slug, type, version]
  - path: "spec/schema"
    line: 190
    keywords: [fields, owner, status, members, services]
  - path: "spec/description"
    line: 155
    keywords: [structure, layers, implicit-group, service-bindings]
  - path: "examples"
    line: 380
    keywords: [minimal, full, services, members]
  - path: "validation"
    line: 430
    keywords: [rules, owner, status, members]

contains:
  - xri: "#identity"
    role: section
    title: "Identity Metadata"
    keywords: [id, slug, type, version]
  - xri: "#spec"
    role: section
    title: "Specification Content"
    keywords: [schema, fields, members, services, federated]
  - xri: "#examples"
    role: section
    title: "Usage Examples"
    keywords: [minimal, full, services]
  - xri: "#validation"
    role: section
    title: "Validation Rules"
    keywords: [required, format, xri]