Protocol Specification

1. Introduction

1.1 Purpose

This document specifies the Tezit Protocol, an open standard for bundling and transmitting knowledge artifacts that preserve reasoning context alongside synthesis.

1.2 Scope

This specification covers:

• Tez bundle format and structure
• Manifest schema
• Context packaging
• Conversation format
• Parameter specification
• Versioning and compatibility
• Extension mechanisms

1.3 Conformance Levels

The Tezit protocol recognizes three conformance levels to support progressive adoption:

1.6 Core Principles

The Library of Context

Original content is preserved forever. Display is regenerable.

When source materials are added to a Tez—voice recordings, documents, raw data—these artifacts are sacred and immutable. The exact words chosen, the original formatting, the raw data values should never be discarded or modified.

Context Travels with Synthesis

A Tez is not a document with attachments. It is a complete unit of understanding where synthesis and supporting context are inseparable.

Interrogation Over Trust

The defining feature of a Tez is that recipients can interrogate it—asking questions that AI answers from the transmitted context alone.

1.7 Tez Profiles

The protocol supports multiple profiles optimized for different use cases:

{
  "profile": "messaging",
  "surface": {
    "message": "Want to see a movie this weekend?",
    "tone": "casual",
    "urgency": "low",
    "actionRequested": "Let me know what works"
  }
}

2. Bundle Structure

2.1 Overview

A Tez bundle is a directory (or archive) containing:

{tez-id}/
├── manifest.json          # REQUIRED
├── tez.md                 # REQUIRED
├── context/               # REQUIRED (may be empty)
│   └── {item-id}.{ext}
├── conversation.json      # OPTIONAL
├── params.json            # OPTIONAL
└── extensions/            # OPTIONAL
    └── {extension-id}/

2.2 Bundle Identifier

The tez-id MUST:

• Be unique within its scope (vault, organization, or global)
• Contain only: lowercase letters, numbers, hyphens
• Be 3-100 characters
• Not start or end with a hyphen

Recommended format: {topic}-{date}-{sequence}

2.3 Archive Format

When distributed as a single file, bundles SHOULD use:

• Extension: .tez
• Format: ZIP with no compression or DEFLATE
• Structure: Bundle root at archive root

3. Manifest Schema

3.1 Full Schema

{
  "$schema": "https://tezit.com/spec/v1/manifest.schema.json",
  "tezit_version": "1.0",
  "id": "string (REQUIRED)",
  "version": "integer (REQUIRED, >= 1)",
  "created_at": "ISO 8601 datetime (REQUIRED)",
  "updated_at": "ISO 8601 datetime (OPTIONAL)",

  "creator": {
    "id": "string (OPTIONAL)",
    "name": "string (REQUIRED)",
    "email": "string (OPTIONAL)",
    "org": "string (OPTIONAL)"
  },

  "profile": "string (OPTIONAL: 'knowledge' | 'messaging')",

  "surface": {
    "message": "string (for messaging profile)",
    "tone": "string ('formal' | 'casual' | 'urgent')",
    "urgency": "string ('critical' | 'high' | 'normal' | 'low')",
    "actionRequested": "string (OPTIONAL)"
  },

  "synthesis": {
    "title": "string (REQUIRED)",
    "type": "string (REQUIRED)",
    "file": "string (REQUIRED, relative path)",
    "abstract": "string (OPTIONAL, max 500 chars)"
  },

  "context": {
    "scope": "string (REQUIRED: 'full' | 'focused' | 'private')",
    "item_count": "integer (REQUIRED)",
    "items": [
      {
        "id": "string (REQUIRED)",
        "type": "string (REQUIRED)",
        "title": "string (REQUIRED)",
        "file": "string (REQUIRED, relative path)",
        "hash": "string (OPTIONAL, format: 'algorithm:hex')"
      }
    ]
  },

  "conversation": {
    "turn_count": "integer",
    "file": "string (relative path)"
  },

  "permissions": {
    "interrogate": "boolean (default: true)",
    "fork": "boolean (default: true)",
    "reshare": "boolean (default: false)"
  }
}

3.2 Required Fields

The following fields MUST be present:

• tezit_version
• id
• version
• created_at
• creator.name
• synthesis.title, synthesis.type, synthesis.file
• context.scope, context.item_count, context.items

3.3 Synthesis Types

Standard synthesis types:

4. Synthesis Format (tez.md)

4.1 Structure

The synthesis file MUST be valid Markdown (CommonMark).

# {Title}

## Executive Summary
{Brief overview}

## {Section 1}
{Content with citations}

## {Section 2}
{Content with citations}

## Conclusion/Recommendation
{Final synthesis}

---
*Tezit v{version} | Context: {count} items | {date}*

4.2 Citations

Citations reference context items using double-bracket syntax:

According to the report [[doc-001]], revenue increased by 15%.

Page-specific: [[doc-001:p12]]
Page range: [[doc-001:p12-15]]
Section: [[doc-001:section-name]]
Timestamp: [[video-001:00:15:30]]

5. Conversation Format

5.1 Schema

{
  "model": "claude-opus-4",
  "model_version": "20250501",
  "turns": [
    {
      "role": "user",
      "content": "Analyze the partnership agreement...",
      "timestamp": "2026-01-15T14:00:00Z"
    },
    {
      "role": "assistant",
      "content": "Looking at the agreement [[doc-001]]...",
      "timestamp": "2026-01-15T14:00:15Z",
      "citations": ["doc-001", "doc-003"]
    }
  ],
  "total_tokens": 15000
}

5.2 Privacy Controls

The conversation may be shared in different modes:

6. Parameters Format

Parameters define negotiable values in a Tez:

{
  "parameters": [
    {
      "name": "revenue_share",
      "type": "range",
      "value": 0.15,
      "constraints": {
        "min": 0.10,
        "max": 0.25,
        "step": 0.01,
        "unit": "percent"
      },
      "preference": 0.15,
      "rationale": "Market data [[doc-003]] suggests 15-20%"
    },
    {
      "name": "payment_terms",
      "type": "options",
      "value": "net-30",
      "constraints": {
        "choices": ["net-15", "net-30", "net-45", "net-60"]
      }
    }
  ]
}

Parameter Types

• range: Numeric values with min/max/step
• options: Discrete choices
• boolean: True/false toggles
• date: Date or date range
• text: Free-form text input

7. Context Packaging

7.1 File Organization

Context items MUST be stored in the context/ directory:

context/
├── doc-001.pdf
├── doc-002.docx
├── email-001.eml
├── data-001.json
└── image-001.png

7.4 Integrity Verification

Content hashes SHOULD use SHA-256:

{
  "id": "doc-001",
  "hash": "sha256:3a7bd3e2360a3d29eea436fcfb7e44c735d117c42d1c..."
}

8. Extensions

Extensions allow protocol enhancement without breaking compatibility.

8.3 Standard Extensions

• tezit-facts: Structured facts extraction with provenance
• tezit-relationships: Entity relationship mapping
• tezit-analytics: Usage analytics
• tezit-signing: Cryptographic signatures
• tezit-encryption: End-to-end encryption

{
  "facts": [
    {
      "id": "fact-001",
      "claim": "Revenue increased 23% year-over-year",
      "confidence": 0.95,
      "source": "verified",
      "citations": ["revenue-report:p3"],
      "category": "financial"
    }
  ]
}

9. Interrogation

Interrogation is the process by which a recipient asks questions about a Tez and receives answers grounded in the transmitted context. This is the core consumption mechanism that enables "trust but verify."

9.1 Grounded Response Requirement

When interrogating a Tez, AI responses MUST be grounded in the transmitted context:

1. Context-only answering: Answer from context items only, not general training
2. Explicit limitations: State clearly when context lacks information
3. No hallucination: All factual claims must be verifiable

9.2 Citation Requirements

All interrogation responses MUST include citations:

The timeline is driven by three integration requirements:

1. **Legacy auth adapter** (2 weeks) [[client-specs:p12]]
2. **Data migration** (2 weeks) [[client-specs:p23]]
3. **Security review** (2 weeks) [[client-specs:p47]]

9.7 Hosting Models

10. Versioning

10.1 Protocol Versioning

Protocol version format: {major}.{minor}

• Major: Breaking changes
• Minor: Backward-compatible additions

10.3 Living Documents

Tezits MAY be configured as living documents with linked context sources that update automatically.

11. Security Considerations