Contracts

UIF Contracts

UIF (Unified Interface Format) contracts are machine-readable descriptions of your React/TypeScript components that capture their structure, behavior, and API. LogicStamp extracts these contracts from your codebase to enable semantic change detection, AI context generation, and contract verification.

What is a UIF Contract?

A UIF contract is a structured representation of a component that includes:

Structural footprint

Variables, hooks, components, and functions used

Logic signature

Props, events, and state that define the component's API

Semantic hash

Unique identifier based on the component's logic (not implementation details)

File hash

Content-based hash for change detection

Contracts are extracted automatically from your TypeScript/React files and embedded in LogicStamp bundles.

Contract Structure

Each UIF contract follows the UIFContract schema (version 0.3):

{
  "type": "UIFContract",
  "schemaVersion": "0.3",
  "kind": "react:component",
  "description": "Component description from JSDoc",
  "version": {
    "variables": ["count", "isOpen"],
    "hooks": ["useState", "useEffect"],
    "components": ["Button", "Card"],
    "functions": ["handleClick", "validate"]
  },
  "logicSignature": {
    "props": {
      "onClick": {
        "type": "function",
        "signature": "() => void"
      },
      "label": {
        "type": "string",
        "optional": false
      }
    },
    "events": {
      "onSubmit": {
        "type": "function",
        "signature": "(data: FormData) => void"
      }
    },
    "state": {
      "isLoading": {
        "type": "boolean"
      }
    }
  },
  "semanticHash": "uif:1a27d0944bbaaf561ee05a01",
  "fileHash": "uif:1f0fa0e2c8958d7fc1696036"
}

Contract Fields

`type`

Always "UIFContract" to identify the contract type.

`schemaVersion`

Schema version string (currently "0.3"). Used for compatibility checking and validation.

`kind`

Component type identifier:

"react:component" – React functional component
"react:hook" – Custom React hook
"typescript:module" – TypeScript module/utility

`version`

Structural composition of the component:

Field	Type	Description
`variables`	`string[]`	Named variables declared in the component
`hooks`	`string[]`	React hooks used (useState, useEffect, etc.)
`components`	`string[]`	Child components imported and used
`functions`	`string[]`	Named functions defined in the component

Note: This captures the structural footprint, not implementation details. Adding a new hook or function changes the version.

`logicSignature`

The public API contract of the component:

`props`

Object mapping prop names to their type information. Includes type, signature (for function props), and optional flag.

`events`

Object mapping event names to their signatures. For React components, these are typically callback props that represent events.

`state`

Object mapping state variable names to their types. Represents the component's internal state structure.

`semanticHash`

Unique hash based on the component's logic and contract.

Changes when: Props, events, state, or structural footprint changes.

Does not change for: Comments, whitespace, or implementation details.

`fileHash`

Content-based hash of the raw file.

Changes when: Any file content modification.

@uif Header Blocks

LogicStamp can extract contracts from JSDoc @uif header blocks in your source files. This allows you to provide explicit contract information or override automatic extraction.

Basic Format

/**
 * @uif Contract
 * @description Button component for user interactions
 * @kind react:component
 */
export function Button({ onClick, label }: ButtonProps) {
  // ...
}

When generating context with --include-code header, LogicStamp includes the @uif header block in the bundle.

What Changes a Contract?

Changes semanticHash

Adding/removing/renaming props
Changing prop types
Adding/removing events
Changing state structure
Adding/removing hooks
Adding/removing child components
Adding/removing named functions

Does Not Change semanticHash

Comments
Whitespace/formatting
Variable names (unless part of public API)
Internal logic refactors
Implementation details

Note: fileHash always changes for any file content modification, including cosmetic changes.

Best Practices

Keep contracts stable – Avoid unnecessary changes to props, events, or state structure

Use semantic hashes – Rely on semanticHash to detect meaningful changes, not fileHash

Document with @uif – Use @uif header blocks for explicit contract documentation

Validate regularly – Run stamp context validate to catch schema drift

Compare before commits – Use stamp context compare to review contract changes