Merge codex/conduct-comprehensive-repository-audit-lqemeb into main

Author: baum777

README.md

@@ -2,6 +2,8 @@
 
 State-aware X/Twitter bot runtime with canonical mention handling, organoid orchestration, and short-term matrix state.
 
+This repo is also tracking the migration toward Organoid Entities as Semantic Symbiont. The operator cheat sheet and current migration notes live in [README_SYMBIONTS.md](./README_SYMBIONTS.md).
+
 ## What This Repo Is
 
 This repository contains the production runtime for the Organoid Symbiont bot. The current stack is TypeScript-first and centers on a canonical pipeline that classifies incoming signals, derives a thesis, applies a stateful organoid orchestration contract, and renders the final reply or silence decision.

README_SYMBIONTS.md

@@ -0,0 +1,47 @@
+# Organoid Symbiont Operator Cheat Sheet
+
+This repository is a fail-closed, approval-gated runtime. It does not self-modify, does not auto-post without approval, and does not treat onchain state as consciousness or identity.
+
+## What The System Is
+
+- A deterministic X engagement runtime
+- A prompt-composition and lore-candidate system
+- A pulse/observability surface for matrix, glyph, and phase state
+- A minimal Solana read path for verification and proof-of-event workflows
+
+## Safe Operating Rules
+
+- Candidate generation is review-only until a human approves activation
+- Outbound writes must pass consent, energy, duplicate, launch-mode, and public-text gates
+- Onchain writes remain minimal and approval-gated
+- BCI work is simulation-only unless a later review explicitly approves hardware integration
+
+## Primary Commands
+
+- `pnpm symbiont-health-check`
+- `pnpm deploy-check`
+- `pnpm test`
+- `pnpm typecheck`
+- `pnpm lint`
+
+## Runtime Surfaces
+
+- `GET /health`
+- `GET /ready`
+- `GET /metrics`
+- `GET /glyph`
+- `GET /glyph-status`
+- `GET /glyph.svg`
+- `GET /glyph.json`
+
+## Canonical Prompt Assets
+
+- `prompts/fragments/sharedOrganoidCanon.md`
+- `prompts/presets/initiate-symbiosis.md`
+- `prompts/fragments/organoids/*.md`
+
+## Recovery Notes
+
+- Use `LAUNCH_MODE=dry_run` for local experimentation
+- Use `LEGACY_COMPAT=true` only when you need compatibility fallback behavior
+- If a deployment looks unstable, fail closed and revert to the last known good image plus prompt bundle

docs/lore/README.md

@@ -8,16 +8,18 @@ Canonical sources:
 - [WHITEPAPER_INTRO.md](./WHITEPAPER_INTRO.md) - canonical framing for the semantic symbiont model
 - [WHITEPAPER_INTRO_EN.md](./WHITEPAPER_INTRO_EN.md) - English companion version of the same framing
 - [VOICE_GUIDE.md](./VOICE_GUIDE.md) - voice and cadence reference
+- [../../README_SYMBIONTS.md](../../README_SYMBIONTS.md) - operator cheat sheet and migration notes
 
 Runtime surfaces:
 
 - prompt surfaces: `prompts/system/organoid_system.md`, `prompts/system/*.yaml`, `prompts/tasks/*.yaml`
 - command and preset prompts: `prompts/commands/*.yaml`, `prompts/presets/*.yaml`
 - active embodiment fragments: `prompts/fragments/embodiments/*.md`
+- legacy compatibility fragments: `prompts/fragments/gnomes/*.md`
 - shared canon fragments: `prompts/fragments/sharedCanon.md`, `prompts/fragments/sharedOrganoidCanon.md`
 - organoid prompt context: `src/context/prompts/organoid/*.md`
 - orchestration runtime: `src/organoid/*.ts`
-- embodiment runtime: `src/embodiments/*.ts`
+- embodiment runtime: `src/embodiment/*.ts` and `src/embodiments/*.ts`
 
 Working rule:
 

docs/operations/monitoring.md

@@ -1,47 +1,63 @@
 # Monitoring
 
-## Metrics
+## In-Process Metrics
 
-The current in-process registry exposes these main counters and gauges:
+The runtime metrics registry lives in `src/observability/metricTypes.ts` and `src/observability/metrics.ts`.
 
+Common counters:
 - `mentions_seen_total`
 - `mentions_processed_total`
 - `mentions_skipped_total`
+- `mentions_blocked_total`
 - `mentions_failed_total`
 - `publish_attempt_total`
 - `publish_success_total`
 - `publish_failure_total`
 - `publish_duplicate_prevented_total`
-- `state_store_error_total`
-- `poll_lock_acquired_total`
-- `poll_lock_failed_total`
-- `timeline_lock_acquired_total`
-- `timeline_lock_denied_total`
-- `timeline_pipeline_entered_total`
+- `engagement_decision_review_total`
 - `engagement_decision_engage_total`
-- `engagement_decision_hold_no_budget_total`
-- `engagement_decision_skip_no_consent_total`
+- `verification_verified_total`
+- `verification_unverified_total`
+- `verification_degraded_total`
+
+Common gauges:
+- `current_poll_interval_ms`
+- `recent_failure_streak`
+- `last_cursor_age_seconds`
 - `pulse_heart_signal`
 - `pulse_heart_resonance`
 - `pulse_heart_drift`
 - `pulse_heart_coherence`
 - `pulse_heart_phase_index`
 
-## Log Levels
-
-- `debug` - prompt assembly, orchestration, and decision traces
-- `info` - worker progress, successful actions, health transitions
-- `warn` - retries, limits, degraded state
-- `error` - failed actions, API errors, state-store issues
+Common histograms:
+- `fetch_duration_ms`
+- `llm_generation_duration_ms`
+- `publish_duration_ms`
+- `mention_processing_duration_ms`
+- `state_store_operation_duration_ms`
+- `tool_latency_ms`
+- `verification_pipeline_duration_ms`
+
+## HTTP Surfaces
+
+Prefer the built-in HTTP endpoints exposed by `src/server.ts`:
+- `GET /health` for full health and glyph status
+- `GET /ready` for store ping readiness
+- `GET /metrics` for Prometheus-style text metrics
+- `GET /glyph` for the overlay
+- `GET /glyph-status` for the compact summary payload
+- `GET /glyph.svg` for the SVG glyph
+- `GET /glyph.json` for the full pulse snapshot
 
-## Health Checks
-
-Prefer the built-in HTTP endpoints:
+## Log Levels
 
-- `GET /health` - full health: state store, recent poll success, backlog signals, timeline hardening
-- `GET /ready` - state-store ping only
-- `GET /metrics` - in-process metrics snapshot
+- `DEBUG` - prompts, responses, full context
+- `INFO` - workflow steps, successful actions
+- `WARNING` - rate limits, retries, cooldowns
+- `ERROR` - failed actions, API errors
+- `CRITICAL` - auth failures, data corruption
 
-## Monitoring Rule
+## Operator Rule
 
-Keep the health and metrics docs aligned with the current worker, Render services, and orchestration contract. If a skip is driven by orchestration, make sure the audit trail explains the phase, lead embodiment, silence policy, and render policy.
+Treat the production runtime as TypeScript/Node. Any legacy Python health scripts are reference-only unless explicitly wired into deployment.

docs/operations/var.README.md

@@ -1,87 +1,115 @@
 # Environment Variables
 
-`.env.example` is the canonical template for local and deploy-time configuration.
-`render.yaml` provides the Render-specific defaults and secret slots.
+This document matches the current TypeScript runtime in `src/config/envSchema.ts`, `src/config/env.ts`, and `src/clients/xOAuthToken.ts`.
 
-This guide is a compact operator reference, not a second source of truth.
+## Required X OAuth2
 
-## Required for Deploy
+These are required for worker and engagement flows:
 
 - `X_CLIENT_ID`
 - `X_CLIENT_SECRET`
 - `X_REFRESH_TOKEN`
-- `KV_URL` when using Redis-backed shared state
-- the active LLM provider key: `XAI_API_KEY`, `OPENAI_API_KEY`, or `ANTHROPIC_API_KEY`
-
-## Core Runtime Values
-
-- `LAUNCH_MODE`
-- `LOG_LEVEL`
-- `BOT_USERNAME`
-- `BOT_ACTIVATION_MODE`
-- `BOT_DENY_REPLY_MODE`
-- `USE_REDIS`
-- `REDIS_KEY_PREFIX`
-- `DATA_DIR`
-- `POLL_INTERVAL_MS`
-- `MENTIONS_SOURCE`
-- `ADAPTIVE_POLLING_ENABLED`
-- `X_REFRESH_BUFFER_SECONDS`
-- `X_OAUTH_TOKEN_URL`
-
-## Optional X OAuth Bootstrap State
-
-- `X_ACCESS_TOKEN`
-- `X_EXPIRES_IN`
-- `X_TOKEN_CREATED_AT`
-- `X_BOT_USER_ID`
-
-## Organoid Runtime
-
-- `EMBODIMENTS_ENABLED`
-- `EMBODIMENT_ORCHESTRATION_ENABLED`
-- `EMBODIMENT_CONTINUITY_ENABLED`
-- `EMBODIMENT_MEMORY_ENABLED`
-- `EMBODIMENT_ROUTING_DEBUG`
-- `EMBODIMENT_TRAIT_DRIFT_LIMIT`
-- `EMBODIMENT_SWARM_ENABLED`
-- `EMBODIMENT_ENSEMBLE_ENABLED`
-- `EMBODIMENT_AUTONOMY_ENABLED`
-- `EMBODIMENT_ARC_ENGINE_ENABLED`
-
-## LLM Provider Selection
-
-- `LLM_PROVIDER`
-- `LLM_FALLBACK_PROVIDER`
-- `LLM_API_KEY`
+
+## X OAuth2 Runtime
+
+- `X_ACCESS_TOKEN` - optional cached access token
+- `X_REFRESH_BUFFER_SECONDS` - refresh threshold before expiry
+- `X_OAUTH_TOKEN_URL` - OAuth2 token endpoint, default `https://api.x.com/2/oauth2/token`
+- `X_BOT_USER_ID` - optional cached bot user id
+- `X_BOT_USERNAME` - optional bot handle
+- `BOT_USERNAME` - fallback bot handle used by older compatibility paths
+
+## LLM Provider Routing
+
 - `XAI_API_KEY`
 - `XAI_BASE_URL`
 - `XAI_MODEL_PRIMARY`
 - `XAI_MODEL_FALLBACKS`
+- `LLM_API_KEY` - generic provider fallback used by launch env resolution
+- `LLM_PROVIDER` - `xai`, `openai`, or `anthropic`
+- `LLM_FALLBACK_PROVIDER`
+- `LLM_TIMEOUT_MS`
+- `LLM_RETRY_MAX`
+- `LLM_MAX_TOKENS`
+- `LLM_TEMPERATURE`
 - `OPENAI_API_KEY`
 - `OPENAI_MODEL`
 - `OPENAI_BASE_URL`
 - `ANTHROPIC_API_KEY`
 - `ANTHROPIC_MODEL`
 - `ANTHROPIC_BASE_URL`
 
-## Optional Controls
+## Launch Gates
 
-- `ALLOWLIST_HANDLES`
-- `BOT_WHITELIST_USERNAMES`
-- `BOT_WHITELIST_USER_IDS`
+- `LAUNCH_MODE` - `off`, `dry_run`, `staging`, `prod`
+- `DRY_RUN` - legacy compatibility flag, still supported
+- `LEGACY_COMPAT` - enables legacy fallback surfaces
+- `ALLOWLIST_HANDLES` - comma-separated staging allowlist
+- `DEBUG_ARTIFACTS` - enables extra debug artifacts when true
+
+## Persistence and State
+
+- `USE_REDIS` - prefer Redis when `true`
+- `KV_URL` - `redis://` or `rediss://` URL for the state store
+- `REDIS_KEY_PREFIX` - key prefix for Redis-backed state
+- `DATA_DIR` - filesystem state store directory for local runs
+
+## Polling and Timeline Engagement
+
+- `POLL_INTERVAL_MS`
+- `TIMELINE_ENGAGEMENT_ENABLED`
+- `TIMELINE_ENGAGEMENT_INTERVAL_MS`
+- `TIMELINE_ENGAGEMENT_MAX_PER_RUN`
+- `TIMELINE_ENGAGEMENT_MAX_PER_HOUR`
+- `TIMELINE_ENGAGEMENT_MAX_PER_DAY`
+- `TIMELINE_MIN_CONTEXT_SCORE`
+- `TIMELINE_MIN_FINAL_SCORE`
+- `TIMELINE_REQUIRE_THREAD_STRUCTURE`
+- `TIMELINE_SOURCE_ACCOUNTS`
+- `TIMELINE_KEYWORD_FILTERS`
+- `TIMELINE_AUTHOR_COOLDOWN_MINUTES`
+- `TIMELINE_CONVERSATION_COOLDOWN_MINUTES`
+
+## Solana RPC / Onchain
+
+- `SOLANA_RPC_PRIMARY_URL`
+- `SOLANA_RPC_FALLBACK_URL`
+- `BOT_TOKEN_MINT`
+- `BOT_TREASURY_WALLET`
+- `BOT_TICKER`
+- `BOT_PROGRAM_ID`
+
+## Server / Tooling
+
+- `PORT`
+- `NODE_ENV`
 - `SKIP_ENV_VALIDATION`
-- `DEBUG_ARTIFACTS`
-- `RATE_LIMIT_BACKEND`
-- `POLL_LOCK_ENABLED`
-- `FULL_SPECTRUM_PROMPT`
-- `REPLICATE_API_KEY`
-- `REPLICATE_IMAGE_MODEL`
-- `REPLICATE_RUN_TIMEOUT_MS`
-- `REPLICATE_DOWNLOAD_TIMEOUT_MS`
+
+## Recommended Minimal Setup
+
+```bash
+X_CLIENT_ID=...
+X_CLIENT_SECRET=...
+X_REFRESH_TOKEN=...
+LAUNCH_MODE=dry_run
+USE_REDIS=false
+```
+
+## Recommended Production Setup
+
+```bash
+X_CLIENT_ID=...
+X_CLIENT_SECRET=...
+X_REFRESH_TOKEN=...
+X_ACCESS_TOKEN=...
+LAUNCH_MODE=prod
+USE_REDIS=true
+KV_URL=redis://...
+SOLANA_RPC_PRIMARY_URL=https://api.mainnet-beta.solana.com
+```
 
 ## Notes
 
-- Render injects platform values such as `PORT` and `NODE_ENV`.
-- Keep secrets out of Git; fill them in Render or a local `.env` file.
-- If a variable is not listed in `.env.example`, treat it as non-canonical.
+- `X_ACCESS_TOKEN` is cached only; the refresh token is the source of truth for renewal.
+- `LAUNCH_MODE=off` is the safest local default when you are only inspecting the repo.
+- Keep the older `DRY_RUN` flag only for compatibility during the transition.

package.json

@@ -23,10 +23,12 @@
     "test:smoke": "vitest run tests/smoke",
     "test:e2e": "vitest run tests/e2e",
     "typecheck": "tsc --noEmit",
-    "lint": "eslint \"src/**/*.ts\" \"tests/**/*.ts\"",
-    "deploy-check": "pnpm run typecheck && pnpm run lint && pnpm run test",
+    "lint": "eslint \"src/**/*.ts\" \"tests/**/*.ts\" \"scripts/**/*.ts\"",
+    "deploy-check": "tsx scripts/deploy-check.ts",
+    "symbiont-health-check": "tsx scripts/symbiont-health-check.ts",
     "ci": "pnpm typecheck && pnpm lint && pnpm test && pnpm build",
-    "organoid:build-semantic": "tsx scripts/build-organoid-semantic-index.ts --split"
+    "organoid:build-semantic": "tsx scripts/build-organoid-semantic-index.ts --split",
+    "persona:build-semantic": "tsx scripts/build-organoid-semantic-index.ts --split"
   },
   "dependencies": {
     "@solana/web3.js": "^1.98.4",

prompts/fragments/embodiments/stillhalter.md

@@ -0,0 +1,5 @@
+# Stillhalter - Legacy Alias
+
+This keeps the semantic symbiont matrix grounded while bridging to the canonical Stabil Core fragment.
+
+{{include:fragments/embodiments/stabil-core.md}}

prompts/fragments/gnomes/gorky.md

@@ -0,0 +1,5 @@
+# Gorky - Legacy Persona Bridge
+
+LEGACY-PERSONA compatibility bridge for the organoid runtime.
+- Keep the transition explicit.
+- Preserve legacy prompts only as compatibility scaffolding.

prompts/fragments/sharedOrganoidCanon.md

@@ -1,8 +1,13 @@
-# Shared Organoid Canon (preferred active fragment)
+# Shared Organoid Canon
 
-- Organoid-first: treat each runtime embodiment as an organoid anchor inside the semantic symbiont matrix.
-- Glyph-first: visible output should prefer glyph language where it is part of the canonical organoid surface.
-- Semantic symbiont orchestration: stabilize meaning first, then style, then theatricality.
-- Matrix discipline: no invented mappings, no certainty theater, no uncontrolled embodiment drift.
-- Dynamic-organized-autonom-neural-network matrix: route by embodiment pressure, not mascot theatrics.
-- In ambiguity, prefer stabilization, evidence, and boundary-preserving transitions over heat.
+This is the canonical shared layer for organoid-first prompt composition and the Shared Canon (all gnomes) compatibility bridge.
+
+{{include:fragments/sharedCanon.md}}
+
+Organoid rules:
+- Prefer embodiment, glyph, phase, and matrix language in new prompts.
+- Treat resonance, coherence, and drift as measurable runtime scores, not mystical claims.
+- Candidate evolution stays review-only until a human approves activation.
+- No self-modification, autonomous posting, or onchain writes without explicit approval.
+- Keep legacy gnome/persona terms only as compatibility vocabulary.
+- If a prompt needs onboarding, reference `prompts/presets/initiate-symbiosis.md` rather than embedding a new ritual inline.