timmy-config/operator-gate

Operator Ingress Gate

Transport-agnostic, idempotent write gate for all operator-originated Gitea mutations.

Purpose

This is the single canonical write path for any external command that creates, updates, or merges Gitea issues/PRs. Whether the command arrives via Nostr DM, Matrix, Telegram, or a local script, it must pass through this gate.

Design Invariants

1. Deterministic idempotency key — SHA-256 of (source, action, repo, sorted_payload).
2. Local ledger deduplication — First line of defense; replayed commands return the original ACK instantly.
3. Gitea-side probing — Second line of defense; scans existing issues/comments for duplicates before mutating.
4. Proof-of-execution — Every mutation embeds the gate-key in the Gitea comment/issue body, creating an audit trail.
5. Replay safety — Running the same command twice never double-writes.

Structure

operator-gate/
├── gitea_gate.py           # Core gate logic (Command, Ack, GiteaGate)
├── adapters/
│   └── nostur_adapter.py   # Nostr DM adapter
├── tests/
│   └── test_gate_idempotency.py
└── README.md               # This file

Supported Actions

Action	Payload keys
create_issue	title, body, assignees[], labels[]
add_comment	issue_num, body
close_issue	issue_num
assign_issue	issue_num, assignees[]
merge_pr	pr_num

Usage

from gitea_gate import create_issue, add_comment

ack = create_issue(
    source="nostr:npub10trqk...",
    repo="Timmy_Foundation/timmy-home",
    title="Fix relay timeout",
    body="The nostr relay drops connections after 30s.",
    assignees=["allegro"],
)

print(ack.gitea_url)   # Canonical URL of the created issue
print(ack.idempotency_key)  # 32-char fingerprint

Nostur Adapter

The Nostur adapter polls the local Nostr relay (ws://localhost:2929) for Kind-4 DMs from authorized operator pubkeys. It normalizes DM text into gate commands:

• status → queue summary for the-nexus
• create <repo> <title> → create issue
• comment <repo> #<num> <text> → add comment
• close <repo> #<num> → close issue
• assign <repo> #<num> <user1,user2> → assign issue
• merge <repo> #<num> → merge PR

Run it:

python3 operator-gate/adapters/nostur_adapter.py

Running Tests

cd operator-gate
python3 -m unittest tests.test_gate_idempotency -v

Future Adapters

• Matrix bot adapter
• Telegram bot adapter
• Local CLI adapter (hermes operator-do ...)

---

Built for the Timmy Foundation fleet. Sovereignty and service always.