@tiinex/app 0.1.1

package/src/transitions/canonical-schema-cache/053d46ce082d4ec261b82abc44ecca403d61e240/tiinex.schema.contract.v1.schema.md

@@ -0,0 +1,391 @@
+# Continuity Context
+
+- Envelope Schema: [tiinex.root.v1](../../tiinex.root.v1.schema.md)
+- Parent
+  - Parent Schema: [tiinex.root.v1](../../tiinex.root.v1.schema.md)
+  - Created At: 2026-06-14 00:00:00
+  - Trace: [tiinex.root.v1.schema.md](../../tiinex.root.v1.schema.md)
+  - Origin:
+    - [browse + git](https://github.com/Tiinex/docs/blob/02392a68bb70f9b1656a77c6c65c272582d05ab1/.topics/.schemas/tiinex.root.v1.schema.md)
+- Current
+  - Current Schema: [tiinex.schema.contract.v1](tiinex.schema.contract.v1.schema.md)
+  - Created At: 2026-07-02 00:00:00
+  - Status: Draft schema proposal
+  - Why: Defines machine-extractable schema contract nodes so schemas can be built, checked, merged, and generated by reliable tooling without requiring an LLM to reinterpret prose every time.
+  - Summary: Schema contract schema for deterministic section, field, value, rule, generation, relation, inheritance, and example contracts.
+
+---
+
+
+# Schema Contract
+
+## Summary
+
+Defines a human-readable and machine-extractable schema contract artifact.
+
+A schema contract turns the parts of a schema that tools need into explicit provenance nodes. It may describe sections, fields, values, rules, generation steps, relations, inheritance, and examples. It is intentionally not a programming language. A human should still be able to read it, and a deterministic tool should be able to extract the declared contract surface without interpreting surrounding prose.
+
+Schema contract does not replace root continuity, schema prose, human judgement, LLM review, validation reports, or implementation code. It identifies the bounded contract that builders, validators, generators, linters, form builders, and presentation tools may rely on.
+
+## Core Semantics
+
+- Schema contract = explicit machine-facing agreement about how a schema artifact may be created, read, checked, generated, or extended.
+- Contract nodes must be separate from explanatory prose.
+- Contract nodes should use scoped handles and continuity fingerprints so validators and builders can reference logical contract nodes and concrete representations without conflating them.
+- Contract nodes may be implemented by humans, LLMs, scripts, CLIs, browser apps, forms, or other tools.
+- A schema contract must say what it covers and what it does not cover.
+- Missing contract nodes must not be silently invented from prose.
+- Prose may explain intent, but the deterministic contract surface must come from declared contract nodes.
+
+## Schema Validation Contract
+
+### Contract Scope
+
+Applies To
+
+- artifacts whose `Current -> Current Schema` is `tiinex.schema.contract.v1`
+
+Rules
+
+- `tiinex.schema.contract.v1` identifies artifacts that expose a bounded machine-extractable contract for schema authoring, validation, generation, inheritance, relation handling, or examples.
+- Schema contract artifacts must preserve contract identity, target schema, declared contract nodes, and contract boundaries.
+- Schema contract artifacts must not imply that all prose in a schema is executable or deterministic.
+- Prose outside `Schema Validation Contract` may explain the schema, but it does not add required validation rules.
+
+### Contract Body
+
+Required Shape
+
+- first body heading after the continuity envelope
+- `## Contract Identity Model` section
+- `## Contract Identity` section
+- `## Contract Target` section
+- `## Contract Nodes` section
+- `## Contract Boundary` section
+- `## Interpretation Limits` section
+
+Optional Sections
+
+- `Deterministic Surface`
+- `Human Surface`
+- `Builder Surface`
+- `Validator Surface`
+- `Generator Surface`
+- `Inheritance Surface`
+- `Relation Surface`
+- `Examples`
+- `Relationship to Other Schemas`
+
+Rules
+
+- Required sections should be understandable without specialized tooling.
+- Contract nodes should be structured enough for tools to extract handles, labels, targets, requirements, conditions, severity, and messages.
+- Optional surfaces must not add contract obligations unless they are explicitly listed under contract nodes.
+
+### Contract Identity Model
+
+Required Fields
+
+- Durable Identity Policy
+- Provisional Handle Policy
+
+Optional Fields
+
+- Continuity Fingerprint
+- Provisional Handle
+- Local Anchor
+- Human Label
+- Scope
+
+Rules
+
+- Scoped contract-node handles may remain logically stable across revisions while they continue to denote the same semantic node inside the owning contract scope.
+- Continuity Integrity fingerprints provide durable references to the concrete representation or declared continuity target they verify; a changed content-derived fingerprint does not by itself create a new logical contract node or supersede its scoped handle.
+- Provisional handles may support authoring, local references, deterministic extraction, and prechecksum generation.
+- Scoped or provisional handles must not silently become global artifact identity.
+- Do not introduce global sequential identifiers for fields, sections, rules, examples, relations, generation steps, annotations, or transitions merely to compensate for representation changes.
+
+### Contract Identity
+
+Required Fields
+
+- Contract Name
+- Contract Kind
+- Contract State
+
+Optional Fields
+
+- Contract Reference
+- Contract Version
+- Contract Owner
+- Contract Stability
+- Contract Profile
+
+Allowed Labels
+
+- schema-contract
+- section-contract
+- field-contract
+- value-contract
+- rule-contract
+- generation-contract
+- relation-contract
+- inheritance-contract
+- example-contract
+- mixed-contract
+- unknown
+
+Rules
+
+- Contract kind should describe the main contract role.
+- Contract state should describe the contract artifact, not whether the target schema is valid.
+
+### Contract Target
+
+Required Fields
+
+- Target Schema
+- Target Scope
+
+Optional Fields
+
+- Target Section
+- Target Field
+- Target Rule
+- Target Node
+- Target Artifact
+- Target Schema Family
+- Parent Schema
+- Child Schema
+
+Rules
+
+- Target schema must identify what schema or schema family this contract describes.
+- Target scope should state whether the contract applies to the whole schema, a section, a field, a rule, a generator, an inheritance relation, or an example.
+- Unresolved targets should be marked unknown rather than inferred.
+
+### Contract Nodes
+
+Entry Shape
+
+- First-Level Hyphen List Item
+
+Required Fields
+
+- Contract Node Type
+- Contract Node Label
+
+Optional Fields
+
+- Applies To
+- Required
+- Optional
+- Cardinality
+- Value Type
+- Condition
+- Operator
+- Severity
+- Message
+- Generation Step
+- Relation Type
+- Parent Binding
+- Child Binding
+- Example Binding
+
+Allowed Labels
+
+- section
+- field
+- value
+- rule
+- generation
+- relation
+- inheritance
+- example
+- presentation
+- module
+- unknown
+
+Rules
+
+- Each first-level entry is one Contract Node declaration.
+- The declaration name is the existing `Contract Node Handle` identity and must be unique within `## Contract Nodes`.
+- Node-local fields belong to that declaration; repeated Node Type/Label/Applies To values must not be paired by document position.
+- Contract node handles are scoped to the target schema contract and may remain stable across revisions while they continue to denote the same semantic node; checksum/fingerprint changes do not automatically supersede the scoped handle.
+- Contract node labels should be human-readable.
+- Contract nodes should not rely on hidden application registries as semantic authority.
+- If a tool cannot understand a contract node type, it should report unknown, unavailable, skipped, or unconfirmed rather than treating it as pass.
+
+### Contract Boundary
+
+Required Fields
+
+- Deterministic Boundary
+- Human Boundary
+
+Optional Fields
+
+- LLM Boundary
+- Tool Boundary
+- Runtime Boundary
+- Out Of Scope
+- Unknown Handling
+
+Rules
+
+- Deterministic boundary must identify which parts are intended to be read by tools without semantic reinterpretation.
+- Human boundary must identify where human judgement or review is still expected.
+- LLM boundary should state whether LLMs may assist creation or review, and what they must not silently decide.
+
+### Interpretation Limits
+
+Required Fields
+
+- Does Not Mean
+- Must Not Be Used To Claim
+
+Optional Fields
+
+- Overclaim Risk
+- Missing Contract Surface
+- Future Work
+
+Rules
+
+- A schema contract must not imply complete semantic understanding of all prose.
+- A schema contract must not imply that deterministic tooling can validate claims, truth, evidence, consent, identity, or source completeness unless separate methods exist.
+
+## Artifact Creation Contract
+
+### Creation Scope
+
+Required Fields
+
+- Create When
+- Do Not Create When
+
+Rules
+
+- Create a schema contract artifact when schema requirements should be reused by builders, validators, generators, linters, modules, or presentation surfaces without reinterpreting prose.
+- Do not create a schema contract artifact merely to restate prose with no extractable handles, targets, conditions, or rules.
+- Use child contracts for specialized section, field, value, rule, generation, relation, inheritance, and example needs.
+
+### Required Inputs
+
+Required Fields
+
+- Target Schema
+- Contract Kind
+- Contract Nodes
+- Deterministic Boundary
+- Interpretation Limits
+
+Optional Fields
+
+- Human Review Boundary
+- LLM Assistance Boundary
+- Builder Surface
+- Validator Surface
+- Generator Surface
+- Examples
+
+Rules
+
+- Missing target, node handles, boundaries, or limits should be explicit.
+- Contract nodes should prefer stable identifiers over display-only labels.
+
+### Generation Rules
+
+Rules
+
+- Start with target schema and contract scope.
+- Identify the contract nodes that should be machine-extractable.
+- Declare requirements, conditions, severity, and messages as fields, not hidden prose.
+- State what remains human or LLM-reviewed.
+- Include examples when they help test the contract.
+
+## Validation-Friendly Shape
+
+- Contract nodes should use root-known category labels such as `Required Fields`, `Optional Fields`, `Allowed Labels`, and `Rules`.
+- A deterministic parser may collect contract nodes by section heading and field labels.
+- Unknown contract node types must be reported as unknown, unavailable, skipped, or unconfirmed rather than silently treated as pass.
+- Examples are illustrative unless explicitly declared as example contracts with expected outcomes.
+
+## Minimal Example
+
+```text
+# Schema Contract: Annotation base
+
+## Contract Identity Model
+
+Durable Identity Policy: scoped contract-node handles preserve logical node reference within the owning contract while Continuity Integrity fingerprints identify concrete representations
+Provisional Handle Policy: readable local handles may be used before checksum without becoming global artifact identity
+
+## Contract Identity
+
+Contract Name: Annotation base contract
+Contract Kind: schema-contract
+Contract State: draft
+
+## Contract Target
+
+Target Schema: tiinex.annotation.v1
+Target Scope: whole-schema
+
+## Contract Nodes
+
+- annotation-target
+  - Contract Node Type: section
+  - Contract Node Label: Annotation Target
+  - Required: true
+
+- target-identifier
+  - Contract Node Type: field
+  - Contract Node Label: Target Identifier
+  - Applies To: annotation-target
+  - Required: true
+  - Value Type: artifact-or-source-reference
+
+- target-identifier-required
+  - Contract Node Type: rule
+  - Contract Node Label: Target Identifier Required
+  - Applies To: target-identifier
+  - Operator: required
+  - Severity: fail
+  - Message: Annotation must identify what is annotated.
+
+## Contract Boundary
+
+Deterministic Boundary: section and field presence can be checked by stable labels and handles
+Human Boundary: semantic quality of the annotation value may still require review
+
+## Interpretation Limits
+
+Does Not Mean: every explanatory sentence in the annotation schema is machine-executable
+Must Not Be Used To Claim: annotation truth, evidence status, or full semantic validation
+```
+
+## Relationship to Other Schemas
+
+- `schema.section` specializes section contracts.
+- `schema.field` specializes field contracts.
+- `schema.value` specializes value-domain contracts.
+- `schema.rule` specializes rule contracts.
+- `schema.generation` specializes generation contracts.
+- `schema.relation` specializes relation contracts.
+- `schema.inheritance` specializes parent-child merge contracts.
+- `schema.example` specializes machine-checkable examples.
+- `condition` may express reusable condition logic used by rules.
+- `schema.module` may bundle contracts with viewers, forms, helpers, and validators.
+
+---
+
+# Continuity Integrity
+
+- sha256-base64url-c14n-v1
+  - Towards: [tiinex.root.v1.schema.md](https://github.com/Tiinex/docs/blob/02392a68bb70f9b1656a77c6c65c272582d05ab1/.topics/.schemas/tiinex.root.v1.schema.md)
+  - Value: pbLraIsPRv4uFdGKSd2WlLHd4vgEqOR2V_PdLDKc_S0
+
+- sha256-base64url-c14n-v2
+  - Towards: self
+  - Value: bNNxvR_nNZnW0mtZGI63VGjC7oOFECNd-9O9gscjds4