Add remove_session behavior contract and unit tests

docs/remove_session_contract.md

@@ -0,0 +1,72 @@
+# remove_session Behavior Contract
+
+## Purpose
+Safely and idempotently remove a session from the SQLite session store.
+
+Integration tests run repeatedly. This function must be reliable and safe to call multiple times.
+
+---
+
+## Function Signature
+
+remove_session --db <db_path> --session-id <id>
+
+---
+
+## Required Parameters
+
+--db (required): Path to SQLite database
+--session-id (required): ID of session to remove
+
+---
+
+## Success Definition
+
+Success means:
+
+If session exists:
+- Session row is deleted
+- Exit code 0
+
+If session does NOT exist:
+- No-op (safe)
+- Exit code 0
+
+Database remains valid and consistent.
+
+---
+
+## Expected DB Changes
+
+DELETE FROM sessions WHERE session_id = ?
+
+No other tables are modified.
+
+---
+
+## Idempotency Guarantee
+
+Calling:
+
+remove_session X
+remove_session X
+
+Produces the same final database state as calling it once.
+
+---
+
+## Failure Modes
+
+Missing DB file -> Exit code 1
+Invalid arguments -> Exit code 2
+SQLite error -> Exit code 3
+
+Errors must log a helpful message to stderr.
+
+---
+
+## Logging Expectations
+
+On success: no output
+On no-op: optional info log
+On failure: descriptive error message

test/helpers/sqlite_fixture.sh

@@ -0,0 +1,22 @@
+#!/usr/bin/env bash
+
+create_test_db() {
+    DB_PATH="$1"
+
+    sqlite3 "$DB_PATH" <<EOF
+CREATE TABLE sessions (
+    session_id TEXT PRIMARY KEY,
+    user_id TEXT,
+    device_id TEXT,
+    created_at TEXT
+);
+
+INSERT INTO sessions VALUES
+('s1', 'u1', 'd1', '2026-02-01'),
+('s2', 'u2', 'd2', '2026-02-01');
+EOF
+}
+
+count_sessions() {
+    sqlite3 "$1" "SELECT COUNT(*) FROM sessions;"
+}

test/remove_session_test.sh

@@ -0,0 +1,71 @@
+#!/usr/bin/env bash
+set -e
+
+source test/helpers/sqlite_fixture.sh
+
+TMP_DB=$(mktemp)
+
+setup() {
+    rm -f "$TMP_DB"
+    create_test_db "$TMP_DB"
+}
+
+teardown() {
+    rm -f "$TMP_DB"
+}
+
+test_remove_existing_session() {
+    setup
+
+    ./remove_session --db "$TMP_DB" --session-id s1
+
+    COUNT=$(count_sessions "$TMP_DB")
+    if [ "$COUNT" -ne 1 ]; then
+        echo "Expected 1 session remaining"
+        exit 1
+    fi
+
+    teardown
+}
+
+test_remove_nonexistent_session() {
+    setup
+
+    ./remove_session --db "$TMP_DB" --session-id does_not_exist
+
+    COUNT=$(count_sessions "$TMP_DB")
+    if [ "$COUNT" -ne 2 ]; then
+        echo "Expected 2 sessions remaining"
+        exit 1
+    fi
+
+    teardown
+}
+
+test_idempotency() {
+    setup
+
+    ./remove_session --db "$TMP_DB" --session-id s1
+    ./remove_session --db "$TMP_DB" --session-id s1
+
+    COUNT=$(count_sessions "$TMP_DB")
+    if [ "$COUNT" -ne 1 ]; then
+        echo "Idempotency failed"
+        exit 1
+    fi
+
+    teardown
+}
+
+test_missing_db() {
+    ./remove_session --db missing.db --session-id s1 && exit 1
+}
+
+echo "Running remove_session tests..."
+
+test_remove_existing_session
+test_remove_nonexistent_session
+test_idempotency
+test_missing_db
+
+echo "All tests passed."