# PyPI Publication Plan - lockstock-integrations v1.1.0

**Date**: 2026-02-05
**Status**: Ready for Publication
**Version**: 1.1.0 (Chain-Based Authentication)

---

## Current Status

### ✅ Completed

1. **Code Implementation**
   - v1.1.0 chain-based authentication implemented
   - `LockStockGuardrail.from_liberty()` uses NO secrets
   - Guard daemon integration complete
   - All integrations updated (OpenAI, LangGraph, Claude)

2. **Documentation**
   - CHANGELOG.md updated with v1.1.0 notes
   - v1.0.1 marked as [YANKED]
   - NO_SECRETS_ARCHITECTURE.md created
   - TEST_VERIFICATION.md documents 7/7 tests passing
   - CLAUDE.md updated with warnings

3. **Testing Infrastructure**
   - test_trinity_lockstock.py updated to v1.1.0 pattern
   - test_e2e_provisioning.py created (comprehensive E2E test)
   - test_chain_sync.py created (chain state verification)
   - test_generator_sync.py exists (generator matrix validation)

4. **Version Configuration**
   - pyproject.toml shows version = "1.1.0"
   - All dependencies specified correctly

### 🚧 Remaining Tasks

1. **Yank v1.0.1 from PyPI**
   - Package was published with WRONG security model
   - Must be yanked to prevent usage
   - Command: `twine yank lockstock-integrations==1.0.1 -r pypi -c "Wrong security model - use v1.1.0"`

2. **Build v1.1.0 Package**
   - Clean old builds
   - Build new wheel and sdist
   - Verify package contents

3. **Publish to PyPI**
   - Upload v1.1.0 to PyPI
   - Verify package appears correctly
   - Test installation

---

## Step-by-Step Publication Process

### Prerequisites

Ensure you have:
- `twine` installed: `pip install twine`
- `build` installed: `pip install build`
- PyPI credentials configured

### Step 1: Yank v1.0.1

```bash
# Yank the incorrect v1.0.1
twine yank lockstock-integrations==1.0.1 -r pypi \
  -c "Wrong security model - use v1.1.0 instead"

# Verify yanked status
# Visit: https://pypi.org/project/lockstock-integrations/1.0.1/
```

### Step 2: Clean Build Directory

```bash
cd lockstock-integrations
rm -rf dist/lockstock_integrations-1.1.0*
rm -rf build/
rm -rf *.egg-info/
```

### Step 3: Build Package

```bash
cd lockstock-integrations
python -m build

# Expected output:
# dist/lockstock_integrations-1.1.0-py3-none-any.whl
# dist/lockstock_integrations-1.1.0.tar.gz
```

### Step 4: Verify Package Contents

```bash
# List wheel contents
unzip -l dist/lockstock_integrations-1.1.0-py3-none-any.whl

# Check for:
# - lockstock_openai/guardrails.py (v1.1.0 chain-based)
# - lockstock_core/client.py
# - lockstock_claude/
# - lockstock_langgraph/
# - All __init__.py files
```

### Step 5: Upload to PyPI

```bash
cd lockstock-integrations
twine upload dist/lockstock_integrations-1.1.0*

# Enter PyPI credentials when prompted
```

### Step 6: Verify Publication

```bash
# Check PyPI page
# https://pypi.org/project/lockstock-integrations/

# Test installation in clean environment
python -m venv test_env
source test_env/bin/activate
pip install lockstock-integrations==1.1.0

# Verify imports work
python -c "from lockstock_openai import LockStockGuardrail; print('OK')"
python -c "from lockstock_core import LockStockClient; print('OK')"
```

---

## Testing Before Publication

### Unit Tests

```bash
cd lockstock-integrations

# Run generator sync test
python tests/test_generator_sync.py
```

### Integration Tests

```bash
# Test with live agent (requires Guard daemon and agent provisioned)
export AGENT_ID="agent_test#1"
export GENESIS_TOKEN="your_token_here"

# E2E provisioning test
python tests/test_e2e_provisioning.py $AGENT_ID $GENESIS_TOKEN

# Chain sync test
python tests/test_chain_sync.py $AGENT_ID
```

### Trinity Test (Full Stack)

```bash
# Full OpenAI agent test with POE API
cd lockstock-integrations
python test_trinity_lockstock.py
```

---

## Post-Publication Verification

### 1. Customer Quickstart Flow

Verify a new customer can:

```bash
# 1. Install from PyPI
pip install lockstock-integrations[openai]

# 2. Provision agent identity
# (Requires genesis token from dashboard)

# 3. Bind with Guard daemon
lockstock-guard bind --agent agent_test#1 --token GENESIS_TOKEN

# 4. Use in code
python -c "
from lockstock_openai import LockStockGuardrail

guardrail = LockStockGuardrail.from_liberty(
    agent_id='agent_test#1',
    socket_path='/var/run/lockstock-guard/guard.sock'
)
print('✓ NO SECRETS USED!')
"
```

### 2. Verify Documentation

Check that PyPI page shows:
- Correct v1.1.0 version
- CHANGELOG with v1.0.1 marked as YANKED
- Installation instructions
- Framework support matrix
- Link to documentation

### 3. Verify GitHub/GitLab

Ensure repository has:
- v1.1.0 git tag
- CHANGELOG.md updated
- README.md accurate
- docs/NO_SECRETS_ARCHITECTURE.md visible

---

## What This Release Fixes

### v1.0.1 Problems (YANKED)

❌ Retrieved secrets from Guard daemon using `guard.get()`
❌ Stored secrets in SDK classes
❌ Violated "secrets never leave daemon" security model
❌ Used persistent secret as HMAC key

### v1.1.0 Solutions

✅ NO secret retrieval or storage
✅ Guard daemon tracks chain state internally
✅ `current_hash` IS the HMAC key
✅ Genesis token is BURNED, not converted to secret
✅ Chain-based authentication throughout

---

## Customer-Facing Message

When customers ask about the v1.0.1 → v1.1.0 change:

> **v1.1.0 implements the correct chain-based authentication model.**
>
> v1.0.1 was yanked because it implemented a secret-storage pattern that violated LockStock's security architecture. In LockStock:
>
> - **Genesis tokens are BURNED** after one use (not stored)
> - **Chain state evolves** with each action (hash, matrix, sequence)
> - **current_hash IS the HMAC key** (no separate persistent secret)
> - **NO secrets exist** anywhere in the system after genesis
>
> **Migration from v1.0.1 to v1.1.0:**
> - API is unchanged - `from_liberty()` works the same
> - Ensure Guard daemon supports `sign_and_advance()` method
> - Ensure Guard daemon has synced chain state from server
> - No code changes required in your agent

---

## Success Criteria

v1.1.0 publication is successful when:

- ✅ v1.0.1 is yanked on PyPI
- ✅ v1.1.0 is published and installable
- ✅ Package contents are correct
- ✅ All tests pass in clean environment
- ✅ Customer quickstart flow works end-to-end
- ✅ Documentation is accurate
- ✅ Audit trail shows topological causal ordering

---

## Contact

If issues arise during publication:
- Check Guard daemon is running: `lockstock-guard status`
- Verify server is accessible: `curl https://lockstock-api-i9kp.onrender.com/health`
- Review audit logs: `https://lockstock-api-i9kp.onrender.com/api/guard/audit`

---

**Ready for Publication**: YES
**Blocking Issues**: NONE
**Next Step**: Execute Step 1 (Yank v1.0.1)

**WE HAVE NO SECRETS TO KEEP!**
