Entity schema

This document describes the entity and relationship schema for the Kibi Knowledge Base. It covers all supported entity types, their properties, relationship types, and provides frontmatter examples for each entity and relationship.

Entity Types

Kibi intentionally supports eight core entity types, organized into two logical groups:

Common Authoring Entities (Standard Workflow)

Supporting & System Entities (Context & Infrastructure)

Entity Choice: When to Use Each Type

This section provides guidance on selecting the appropriate entity type for your documentation needs.

Decision Table

Important Rules

Do NOT create a flag for bugs or workarounds unless there is an actual runtime/config gate. Use fact with fact_kind: observation or meta instead.

When a bug is mitigated by a feature gate: Create TWO records - a fact describing the issue and a flag representing the gate. Link them with relates_to since no typed relationship exists for this case.

Canonical Mapping Summary

• flag = Runtime/config gate (includes kill-switches, deferred capabilities) - NOT for bug records
• fact (observation/meta) = Bug records, incident notes, workarounds
• req = Intended/corrected behavior
• test = Executable verification/reproduction
• adr = Durable design rationale

Common Properties (All Entities)

Entity Type Details & Example Frontmatter

Requirement (req)

Canonical Example: REQ + SCEN + TEST (Golden Path)

# .kb/requirements/REQ-auth-login.md
---
id: REQ-auth-login
title: User authentication
status: open
created_at: 2026-03-10T10:00:00Z
updated_at: 2026-03-10T10:00:00Z
source: .kb/requirements/REQ-auth-login.md
links:
  - type: specified_by
    target: SCEN-auth-login-success
---

# .kb/scenarios/SCEN-auth-login-success.md
---
id: SCEN-auth-login-success
title: Login with valid credentials
status: active
created_at: 2026-03-10T10:01:00Z
updated_at: 2026-03-10T10:01:00Z
source: .kb/scenarios/SCEN-auth-login-success.md
---

# .kb/tests/TEST-auth-login-success.md
---
id: TEST-auth-login-success
title: Login test
status: passing
created_at: 2026-03-10T10:02:00Z
updated_at: 2026-03-10T10:02:00Z
source: .kb/tests/TEST-auth-login-success.md
links:
  - type: validates
    target: SCEN-auth-login-success
---

Generic Link Shorthand:

links:
  - ADR-session-token-storage
  - FACT-auth-session-ttl

Plain string Markdown links entries are imported as generic relates_to relationships. Use typed link objects or relationship rows when the semantic relationship matters.

Relationship Rows Example:

# Relationship: REQ-auth-login specified_by SCEN-auth-login-success
relationship:
  type: specified_by
  source: REQ-auth-login
  target: SCEN-auth-login-success
  created_at: 2026-03-10T10:03:00Z
  created_by: analyst
  source: .kb/requirements/REQ-auth-login.md
---
# Relationship: REQ-auth-login verified_by TEST-auth-login-success
relationship:
  type: verified_by
  source: REQ-auth-login
  target: TEST-auth-login-success
  created_at: 2026-03-10T10:04:00Z
  created_by: qa
  source: .kb/requirements/REQ-auth-login.md

Rule: Never embed scenarios or tests inside requirement records. Always create separate files for each entity and link them with explicit typed links entries or relationship rows (specified_by, verified_by). Plain string links are generic relates_to only.

Strict Fact Modeling (Normative Lane):

• Preserve readable requirement prose, but decompose the entire assertive body into atomic propositions with kb_semantic_advisor. Context-only rationale, examples, and subjective commentary remain in the inventory as nonlogical and do not enter logic_claims.

• For a current requirement write, persist the receipt's inventory_contract as semantic_inventory_version, semantic_source_field, and semantic_source_hash. Ledger spans are UTF-8 byte offsets into that exact field; the advisor canonicalizes repeated identical normalized claims to one proposition at the first source occurrence, while duplicate keys/spans in a submitted ledger, source drift, and silent omission are rejected before mutation.

• Store exactly all returned assertive keys in the requirement logic_claims manifest. Each modeled entry must resolve through exactly one requires_property, requires_predicate, or requires_rule edge to a fact carrying the same claim_key; explicit ambiguous, ontology_gap, or missing entries remain ingestible but unresolved.

• logic-coverage checks manifest-to-ground-fact correspondence and is enabled by default. Requirements without manifests remain a gradual-backfill case; quality diagnostics identify every current requirement with this debt, while the default rule prevents explicitly modeled manifests from drifting.

• New contradiction-sensitive requirements should use the strict fact lane:

  • one fact_kind: subject fact linked via constrains
  • one fact_kind: property_value fact linked via requires_property

• For v1, the supported evolution path is append-only: create a new requirement and link it to the prior one with supersedes.

• Automated modeling via kb_model_requirement can produce deterministic write plans. /kibi-bootstrap returns kibi.bootstrap-plan.v1; bootstrap writes require a user-facing preview and explicit approval before calling kb_apply_plan.

• Low-confidence downgrade: If confidence is < 0.7, requirements are downgraded to observation facts to avoid false-positive contradictions.

• Use observation and meta facts for runtime evidence, historical notes, and governance context that should not participate in contradiction blocking.

Canonical Contradiction-Safe Example:

# .kb/facts/FACT-USER-ROLE.md
---
id: FACT-USER-ROLE
title: User Role Assignment
status: active
created_at: 2026-03-24T00:00:00Z
updated_at: 2026-03-24T00:00:00Z
source: .kb/facts/FACT-USER-ROLE.md
fact_kind: subject
subject_key: user.role_assignment
---

# .kb/facts/FACT-LIMIT-3.md
---
id: FACT-LIMIT-3
title: Maximum of Three
status: active
created_at: 2026-03-24T00:00:00Z
updated_at: 2026-03-24T00:00:00Z
source: .kb/facts/FACT-LIMIT-3.md
fact_kind: property_value
subject_key: user.role_assignment
property_key: max_roles
operator: lte
value_type: int
value_int: 3
---

# .kb/requirements/REQ-user-role-limits.md
---
id: REQ-user-role-limits
title: Users can now have 3 roles
status: open
created_at: 2026-02-20T13:06:00Z
updated_at: 2026-03-24T00:00:00Z
source: .kb/requirements/REQ-user-role-limits.md
links:
  - type: constrains
    target: FACT-USER-ROLE
  - type: requires_property
    target: FACT-LIMIT-3
  - type: supersedes
    target: REQ-user-role-assignment
---

**Schema Migration:**

Older KBs can be upgraded to the latest schema using the `migrate` command. This ensures all entities are compatible with the latest contradiction and validation rules.

```bash
# Check if migration is required
kibi status

# Perform the migration
kibi migrate --yes

Schema version 2 introduces strict symbol granularity. During migration, existing coarse file/module links that can be explained by older ontology data are marked with granularity_reason: legacy-link; new or updated symbol traceability should target the narrow function, class method (ClassName.methodName), class, or other behavioral symbol whenever one exists. Interfaces, type aliases, and enums are type-shape symbols; they describe code shape and do not by themselves block a coarse behavioral link.

Invalid Example (Prohibited):

# WRONG - embedded scenario
---
id: REQ-auth-login
title: User authentication
scenarios:
  - given: user is on login page
    when: they enter valid credentials
    then: they are logged in
---

Scenario (scenario)

Example:

---
id: SCEN-auth-login-success
title: Sample scenario SCEN-auth-login-success
status: active
created_at: 2026-02-17T13:00:00Z
updated_at: 2026-02-17T13:00:00Z
source: https://example.com/fixtures/scenarios/SCEN-auth-login-success
tags:
  - sample
---

Test (test)

proof_receipts is append-only: never remove or rewrite existing entries, and include the full history when authoring a test file directly. Receipts are engine-derived from kibi.proof-run.v1 producer artifacts — see proving requirements for contracts, the kibi prove workflow, and the artifact reference.

tags remain metadata only. They do not alias or replace typed verification fields.

Coverage-depth reporting uses typed verification fields before legacy hints. A test with status: passing and verification_scope: end_to_end supplies structural depth evidence even if it has no e2e tag; tag or path heuristics are only fallback evidence for older records. Durable status never supplies conservative proof evidence by itself. Requirement coverage rows can therefore report deterministic depth labels without changing the underlying covered/uncovered decision:

• direct_passing_e2e — the requirement is directly linked to a passing e2e test.
• scenario_passing_e2e — a linked scenario is validated by a passing e2e test.
• unit_only — passing evidence exists, but only at unit scope.
• open_or_nonpassing_tests_only — tests exist but none are passing.
• scenario_only_no_test — scenarios exist without executable test evidence.
• no_test_evidence — no scenario or test evidence is linked.

Conservative requirement proof uses receipt history instead. Each kibi.proof-receipt.v1 binds receipt_id, test_id, typed scope, outcome, code_snapshot, environment_hash, started_at, finished_at, artifact_digest, contract_hash, execution fingerprint, integration_id, producer, and command_argv. History is capped at 50 entries, receipt IDs are unique, finish times increase strictly, and existing entries cannot be removed, changed, or reordered through upsert or incremental sync. Proof accepts only the newest receipt for the deterministic current workspace snapshot when it passed, is not future-dated, and is at most seven days old. Missing, wrong-snapshot, stale, failed, malformed, or future-dated evidence produces explicit proof gaps.

kibi.workspace-snapshot.v2 hashes current versionable code plus requirement, scenario, fact, test-contract, and symbol-manifest inputs. It excludes .kb/ derived runtime trees, release changesets, general docs/, and the proof_receipts frontmatter field inside every tracked Markdown file, preventing a receipt from invalidating its own code hash without hiding changes to the surrounding test contract. A receipt bound to an older snapshot hash is not proof of the current snapshot. Rerun kibi prove so the receipt matches the snapshot the branch is on now.

Check output diagnostics

kibi check, MCP kb_check, staged impact checks, and OpenCode scheduled checks use a two-lane output contract rather than modeling audit findings as new entity types:

• violations[] is the hard correctness lane. Graph, schema, contradiction, query-plan, and staged blocking failures stay here and continue to fail checks.
• qualityDiagnostics[] is the audit-quality lane. Modeling reviews, coverage-depth reviews, broad requirement fanout, duplicate coordinates, symbol fanout, status misuse, and strict-fact modeling suggestions are advisory unless a diagnostic explicitly sets blocking: true or severity: "error".

The public severity values are error, warning, review, and info. review and info do not fail checks by default; warning is also non-blocking unless paired with blocking: true. Integrations should inspect both severity and blocking instead of treating every diagnostic-like record as a failure.

Example:

---
id: TEST-auth-login-success
title: Sample test TEST-auth-login-success
status: passing
created_at: 2026-02-17T13:00:00Z
updated_at: 2026-02-17T13:00:00Z
source: https://example.com/fixtures/tests/TEST-auth-login-success
tags:
  - sample
verification_scope: end_to_end
verification_perspective: consumer
proof_contract:
  version: kibi.proof-contract.v1
  integration: self-proof
  required_proofs:
    - symbol_id: SYM-test-auth-login-success
      target: default
  success_policy: all_required_first_attempt
proof_receipts:
  - version: kibi.proof-receipt.v1
    receipt_id: PR-TEST-auth-login-success-20260217T1305
    test_id: TEST-auth-login-success
    scope: end_to_end
    outcome: passed
    code_snapshot: aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa
    environment_hash: bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb
    started_at: 2026-02-17T13:00:00Z
    finished_at: 2026-02-17T13:05:00Z
    artifact_digest: cccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccc
    contract_hash: dddddddddddddddddddddddddddddddddddddddddddddddddddddddddddddddd
    fingerprint: eeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee
    fingerprint_components:
      contract: 111111111111111111111111111111111111111111111111111111111111111a
      integration: 222222222222222222222222222222222222222222222222222222222222222a
      command: 333333333333333333333333333333333333333333333333333333333333333a
      bindings: 4444444444444444444444444444444444444444444444444444444444444444a
      producer: 5555555555555555555555555555555555555555555555555555555555555555a
    integration_id: self-proof
    producer:
      name: kibi-command-producer
    command_argv: [node, scripts/run-proof-producer.mjs]
    run_outcome: passed
    proof_results:
      - symbol_id: SYM-test-auth-login-success
        target: default
        outcome: passed
        binding: aggregate_run
        attempts:
          status: unavailable
---

See docs/examples/test-verification-fields.md for a complete example using both typed fields.

ADR (adr)

Example:

---
id: ADR-session-token-storage
title: Sample ADR ADR-session-token-storage
status: accepted
created_at: 2026-02-17T13:00:00Z
updated_at: 2026-02-17T13:00:00Z
source: https://example.com/fixtures/adrs/ADR-session-token-storage
tags:
  - architecture
---

Flag (flag)

Example:

---
id: FLAG-login-rate-limit
title: Sample flag FLAG-login-rate-limit
status: active
created_at: 2026-02-17T13:00:00Z
updated_at: 2026-02-17T13:00:00Z
source: https://example.com/fixtures/flags/FLAG-login-rate-limit
tags:
  - rollout
---

Event (event)

Example:

---
id: EVT-user-logged-in
title: Sample event EVT-user-logged-in
status: active
created_at: 2026-02-17T13:00:00Z
updated_at: 2026-02-17T13:00:00Z
source: https://example.com/fixtures/events/EVT-user-logged-in
tags:
  - domain
---

Symbol (symbol)

Example:

---
id: SYM-login-handler
title: Sample symbol SYM-login-handler
status: active
created_at: 2026-02-17T13:00:00Z
updated_at: 2026-02-17T13:00:00Z
source: https://example.com/fixtures/symbols/SYM-login-handler
tags:
  - code
---

Fact (fact)

Facts support two authoring lanes:

• Strict lane for normative, contradiction-sensitive knowledge
  • subject: requires subject_key
  • property_value: requires subject_key, property_key, operator, value_type, and exactly one value field
• Context lane for non-blocking knowledge
  • observation
  • meta
• Ontology lane for project-local predicate modeling
  • predicate_schema: defines an allowed predicate signature; requires predicate_name, predicate_arity, argument_names, and argument_types. May close argument vocabularies with argument_constants (allowed values keyed by argument name) and argument_aliases (legacy spellings keyed by argument name, each mapped to a declared constant); unlisted arguments stay open
  • predicate: stores a ground predicate claim; requires predicate_name, non-empty predicate_args, and canonical_key; may use polarity: assert or deny; logical coverage also uses the paired claim_key and claim_text provenance fields
• Logic lane for conditional and modal requirements
  • rule_schema: declares the stable kibi.logic.v1 signature used by rule facts
  • rule: stores schema-validated canonical Logic IR JSON, a full rule_hash, semantic key, provenance span, and rule_schema_id

Legacy prose facts without fact_kind remain readable during migration, but new requirements should prefer the strict lane when the fact expresses a rule that should block contradictions.

fact entities represent atomic domain concepts and invariants (for example domain nouns, cardinalities, property values, ontology predicates, and safe rules). Requirements can link to strict facts using constrains and requires_property, ontology predicate facts using requires_predicate, or safe Logic IR rules using requires_rule, so domain claims become structural and queryable. When either claim_key or claim_text is supplied, both are required.

Migration note: schema v4 adds semantic_inventory, its source-binding contract, rule_schema, rule, and requires_rule additively. Existing Markdown requirements receive a one-time semantic-hash baseline; the next semantic edit, or any newly added requirement after that baseline, must carry a complete ledger. Projects can adopt the logic lane incrementally by preserving advisor proposition ledgers, adding rule schemas, then linking modeled requirements to safe facts while leaving unresolved states explicit.

Logic IR facts

rule_ir is a JSON object with version: kibi.logic.v1; it is validated and canonicalized before persistence. It supports typed atoms, variables, conjunction/disjunction, comparisons, bounded counts, temporal intervals, exceptions, and the modalities assert, deny, oblige, permit, and forbid. rule_hash is the full SHA-256 of canonical IR; semantic_key is a shorter stable identity for paraphrase convergence. Kibi renders Prolog for inspection, but never evaluates stored source text. rule-safety and rule-verifiability are blocking checks for new rule records.

Requirements also retain a semantic_inventory proposition ledger. Each entry binds a claim key and exact claim text to a UTF-8 byte span and one of modeled, ambiguous, ontology_gap, nonlogical, or missing. An assertive proposition that is not modeled must be explicitly unresolved; prose alone is not logical coverage.

Symbol coordinates are generated compiler state. Callers cannot author sourceLine, sourceColumn, sourceEndLine, or sourceEndColumn through kb_upsert: source-first symbol upserts re-extract the canonical manifest plus .kb/symbol-coordinates.yaml before committing, so partial payloads can no longer erase persisted coordinates, and coordinate refresh failures abort the mutation instead of being reported as complete. The artifact is version 2: every record carries an identity hash bound to the extraction that produced it, malformed artifacts fail sync and mutations closed, and publication is atomic. This lets conservative proof reporting validate the exact source-bound symbols that carry implementation and executable-test evidence; the authored manifest remains coordinate-free and .kb/symbol-coordinates.yaml remains the generated source of truth.

Example:

---
id: FACT-USER-ROLE
title: User Role Assignment
status: active
created_at: 2026-02-20T13:00:00Z
updated_at: 2026-02-20T13:00:00Z
source: .kb/facts/FACT-USER-ROLE.md
tags:
  - domain
  - auth
---

Relationship Types

Kibi supports relationship types listed below. Each relationship has metadata:

Relationship Table

Relationship Examples

depends_on

# req REQ-auth-login-lockout depends_on req REQ-auth-login
relationship:
  type: depends_on
  source: REQ-auth-login-lockout
  target: REQ-auth-login
  created_at: 2026-02-17T13:10:00Z
  created_by: analyst
  source: https://example.com/fixtures/requirements/REQ-auth-login-lockout

specified_by

# req REQ-auth-login specified_by scenario SCEN-auth-login-success
relationship:
  type: specified_by
  source: REQ-auth-login
  target: SCEN-auth-login-success
  created_at: 2026-02-17T13:15:00Z
  created_by: analyst
  source: https://example.com/fixtures/requirements/REQ-auth-login

verified_by

# req REQ-auth-login verified_by test TEST-auth-login-success
relationship:
  type: verified_by
  source: REQ-auth-login
  target: TEST-auth-login-success
  created_at: 2026-02-17T13:20:00Z
  created_by: qa
  source: https://example.com/fixtures/tests/TEST-auth-login-success

verified_by has one frozen meaning: a requirement or scenario is verified by a test. Direct req -> test is fallback only when no scenario exists. Prefer req -> scenario -> test.

Facts are not directly verified by tests. Model the behavior through a requirement: link the requirement to strict or observation facts with constrains, requires_property, or requires_predicate, then link the requirement or scenario to the test with verified_by / validates.

validates

# test TEST-auth-login-success validates scenario SCEN-auth-login-success
relationship:
  type: validates
  source: TEST-auth-login-success
  target: SCEN-auth-login-success
  created_at: 2026-02-17T13:22:00Z
  created_by: qa
  source: https://example.com/fixtures/tests/TEST-auth-login-success

validates is the inverse edge for req/scenario ↔ test links.

implements

# symbol SYM-login-handler implements req REQ-auth-login
relationship:
  type: implements
  source: SYM-login-handler
  target: REQ-auth-login
  created_at: 2026-02-17T13:25:00Z
  created_by: dev
  source: https://example.com/fixtures/symbols/SYM-login-handler

implements is frozen to requirement ownership only (symbol -> req).

covered_by

# symbol SYM-login-handler covered_by test TEST-auth-login-success
relationship:
  type: covered_by
  source: SYM-login-handler
  target: TEST-auth-login-success
  created_at: 2026-02-17T13:30:00Z
  created_by: dev
  source: https://example.com/fixtures/tests/TEST-auth-login-success

covered_by is frozen to production coverage evidence only (symbol -> test).

executable_for

# symbol SYM-test-auth-login-success executable_for test TEST-auth-login-success
relationship:
  type: executable_for
  source: SYM-test-auth-login-success
  target: TEST-auth-login-success
  created_at: 2026-02-17T13:32:00Z
  created_by: dev
  source: https://example.com/fixtures/symbols/SYM-test-auth-login-success

executable_for is frozen to executable test code identity only (symbol -> test).

For the canonical symbol taxonomy, integration/e2e N/A rubric, and anti-blanket requirement checklist, see Symbol Traceability Taxonomy.

constrained_by

# symbol SYM-login-handler constrained_by adr ADR-session-token-storage
relationship:
  type: constrained_by
  source: SYM-login-handler
  target: ADR-session-token-storage
  created_at: 2026-02-17T13:35:00Z
  created_by: architect
  source: https://example.com/fixtures/adrs/ADR-session-token-storage

guards

# flag FLAG-login-rate-limit guards req REQ-auth-login
relationship:
  type: guards
  source: FLAG-login-rate-limit
  target: REQ-auth-login
  created_at: 2026-02-17T13:45:00Z
  created_by: devops
  source: https://example.com/fixtures/flags/FLAG-login-rate-limit

publishes

# symbol SYM-login-handler publishes event EVT-user-logged-in
relationship:
  type: publishes
  source: SYM-login-handler
  target: EVT-user-logged-in
  created_at: 2026-02-17T13:50:00Z
  created_by: dev
  source: https://example.com/fixtures/symbols/SYM-login-handler

consumes

# symbol SYM-login-handler consumes event EVT-user-logged-in
relationship:
  type: consumes
  source: SYM-login-handler
  target: EVT-user-logged-in
  created_at: 2026-02-17T13:55:00Z
  created_by: dev
  source: https://example.com/fixtures/symbols/SYM-login-handler

constrains

# req REQ-user-role-assignment constrains fact FACT-USER-ROLE
relationship:
  type: constrains
  source: REQ-user-role-assignment
  target: FACT-USER-ROLE
  created_at: 2026-02-20T14:00:00Z
  created_by: analyst
  source: .kb/requirements/REQ-user-role-assignment.md

requires_property

# req REQ-user-role-assignment requires_property fact FACT-LIMIT-2
relationship:
  type: requires_property
  source: REQ-user-role-assignment
  target: FACT-LIMIT-2
  created_at: 2026-02-20T14:01:00Z
  created_by: analyst
  source: .kb/requirements/REQ-user-role-assignment.md

relates_to

# Generic relationship between any two entities
relationship:
  type: relates_to
  source: ENTITY-A
  target: ENTITY-B
  kind: custom
  created_at: 2026-02-17T14:00:00Z
  created_by: analyst
  source: https://example.com/fixtures/entities/ENTITY-A

supersedes

# adr ADR-session-token-storage-v2 supersedes adr ADR-session-token-storage
relationship:
  type: supersedes
  source: ADR-session-token-storage-v2
  target: ADR-session-token-storage
  created_at: 2026-02-20T10:00:00Z
  created_by: architect
  source: https://example.com/fixtures/adrs/ADR-session-token-storage-v2

restates

# req REQ-billing-invoice-retention restates req REQ-platform-record-retention
relationship:
  type: restates
  source: REQ-billing-invoice-retention
  target: REQ-platform-record-retention
  created_at: 2026-09-28T10:00:00Z
  created_by: analyst
  source: .kb/requirements/REQ-billing-invoice-retention.md

Notes

• The schema is the eight entity types and the relationship catalog in this document.
• IDs must be stable and unique. Set an explicit frontmatter id named by what the entity governs (<TYPE>-<area>-<behavior>, e.g. REQ-cli-gc) and keep the filename stem equal to it; never pick the next free number. A missing id falls back to a path-and-title hash that changes on rename. entity-id-style reports stem mismatches and newly created numeric IDs; legacy numbered entities are grandfathered.
• Relationship metadata supports audit and conflict resolution.
• Status values are entity-type specific (see above).

End of schema documentation.